From c0210abaeef7ee8412e1da7f2acd8edec2412d9e Mon Sep 17 00:00:00 2001 From: Hu Zhao <zhao@mbd.rwth-aachen.de> Date: Mon, 12 Dec 2022 16:59:37 +0100 Subject: [PATCH] docs: add documentation for mass point model --- docs/source/simulator/mass_point_model.rst | 73 ++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/docs/source/simulator/mass_point_model.rst b/docs/source/simulator/mass_point_model.rst index c21845a..a4ee7e3 100644 --- a/docs/source/simulator/mass_point_model.rst +++ b/docs/source/simulator/mass_point_model.rst @@ -1,6 +1,79 @@ Mass Point Model ================ +Theory of mass point model +-------------------------- + +A `mass point model` is an extremely simplified model to simulate the movement +of some mass on a given topography. It assumes that the flow mass is condensed +to a single point. + +Let :math:`Z(x,y)` define a topography in a Cartesian +coordinate system :math:`\{x, y, z\}`. It induces a local non-orthogonal +coordinate system :math:`\{T_x, T_y, T_n\}`, where :math:`T_x` and :math:`T_y` +denote surface tangent directions and :math:`T_n` denote surface normal direction +:math:`T_n`, as shown by the following figure :cite:p:`Zhao2021b` + +.. image:: ../_static/coordinate_system.png + :width: 300 + :alt: a surface-induced coordinate system + :align: center + +The govening equations describing the movement of a masspoint on the surface are +given by + +.. math:: \frac{d x}{d t} = U_{T_x} \frac{1}{\sqrt{1+\left(\partial_x Z(x, y)\right)^2}} + :label: dxdt + +.. math:: \frac{d y}{d t} = U_{T_y} \frac{1}{\sqrt{1+\left(\partial_y Z(x, y)\right)^2}} + :label: dydt + +.. math:: \frac{d U_{T_x}}{d t}=g_{T_x} - \frac{U_{T_x}}{\|\boldsymbol{U}\|} + \cdot \left(\mu\left(g_N+\boldsymbol{U}^T \boldsymbol{K} \boldsymbol{U}\right) + + \frac{g}{\xi}\|\boldsymbol{U}\|^2\right) + :label: dUTxdt + +.. math:: \frac{d U_{T_y}}{d t} = g_{T_y} - \frac{U_{T_y}}{\|\boldsymbol{U}\|} + \cdot\left(\mu\left(g_N+\boldsymbol{U}^T \boldsymbol{K} \boldsymbol{U}\right) + + \frac{g}{\xi}\|\boldsymbol{U}\|^2\right) + :label: dUTydt + +where :math:`\mu` and :math:`\xi` are dry-Coulomb and turbulent friction coefficients +respectively. :math:`\mathbf{K}` is the curvature tensor :cite:p:`Fischer2012`. +:math:`\mathbf{U}` prepresents the masspoint's velocity. :math:`U_{T_x}` and +:math:`U_{T_y}` are the velocity components along :math:`T_x` and :math:`T_y` direction +respectively. + +Equations :eq:`dxdt` to :eq:`dUTydt` can be rewritten in vector format as + +.. math:: \frac{d \boldsymbol{\alpha}}{d t}=\boldsymbol{f}(t, \boldsymbol{\alpha}) + :label: dalphadt + +.. math:: \boldsymbol{\alpha}=\left[\begin{array}{c} + x(t) \\ + y(t) \\ + U_{T_x}(t) \\ + U_{T_y}(t) + \end{array}\right] + :label: alpha + +.. math:: \boldsymbol{f}=\left[\begin{array}{c} + U_{T_x} \frac{1}{\sqrt{1+\left(\partial_x Z(x, y)^2\right.}} \\ + U_{T_y} \frac{1}{\sqrt{1+\left(\partial_y Z(x, y)^2\right.}} \\ + g_{T_x}-\frac{U_{T_x}}{\|\boldsymbol{U}\|} \cdot\left(\mu\left(g_N+\boldsymbol{U}^T + \boldsymbol{K} \boldsymbol{U}\right)+\frac{g}{\xi}\|\boldsymbol{U}\|^2\right) \\ + g_{T_y}-\frac{U_{T_y}}{\|\boldsymbol{U}\|} \cdot\left(\mu\left(g_N+\boldsymbol{U}^T + \boldsymbol{K} \boldsymbol{U}\right)+\frac{g}{\xi}\|\boldsymbol{U}\|^2\right) + \end{array}\right] + :label: vector-f + +Equation :eq:`dalphadt` define an initial value problem. Given initial +:math:`\boldsymbol{\alpha}_0`, the system can be solved forward in time using +numerical schemes such as the runge-kutta method. Class :class:`.MassPointModel` +utilizes the explicit runge-kutta method ``dopri5`` provided by +:class:`scipy.integrate.ode`. + + MassPointModel Class -------------------- -- GitLab