Differences

This shows you the differences between two versions of the page.

--- documentation:tech_specs [00:29 24.07.2013] – [Diffusion] Walter
+++ documentation:tech_specs [22:02 02.08.2013] (current) – [Random numbers] Walter
@@ Line 1: / Line 1: @@
-~~NOTOC~~
 ====== Technical specification ======
-==== Overview ====
-Morpheus is built out of the following building blocks:
-  * **[[documentation:tech_specs#Solvers|Equation solvers]]**: numerical solvers for systems of (differential) equations (ODE, SDE, PDE)
-  * **[[documentation:tech_specs#Lattice|Lattice]]**: space discretization for both PDEs and discrete cell models (e.g. CPM)
-  * **[[documentation:tech_specs#Diffusion|Diffusion]]**: redistribution of concentration of species in PDE
-  * **[[documentation:tech_specs#Motility|Motility]]**: cell shape and motility of discrete cells in CPM
-These components can be combined into complex models using
-  * **[[documentation:tech_specs#Model integration|Automated model integration]]**: scheduling and spatial mapping
-New features can be added through implementation of
-  * **[[documentation:tech_specs#Plugins|Plugins]]**: framework for extensibility, based on various plugin interfaces
-[{{ :documentation:tech_specs:morpheusstructure_small.gif?direct |Multi-scale models are constructed by combining various modules.}}]
 ===== Solvers =====
-=== Ordinary differential equations ===
+==== Ordinary differential equations (ODE) ====
-Morpheus implements various explicit finite different solvers of numerical integration of **ODEs**:
+Morpheus implements explicit finite different solvers of numerical integration of ODEs:
   * [[http://en.wikipedia.org/wiki/Euler_method|Euler's method]]: 1st order
@@ Line 31: / Line 12: @@
   * [[http://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_method|Runge-Kutta's method]]: 4th order
-=== Stochastic differential equations ===
+and stochastic differential equations (SDEs):
-In addition, Morpheus implements a method to scale the noise amplitude in stochastic ODEs (**SDEs**):
-  * [[http://en.wikipedia.org/wiki/Euler%E2%80%93Maruyama_method|Euler-Maruyama's method]].
+  * [[http://en.wikipedia.org/wiki/Euler%E2%80%93Maruyama_method|Euler-Maruyama's method]] for 1st and 2nd order.
-The latter is used automatically when using Euler or Heun method with a noise term. **Note**: Maruyama's method is not available when using Runge-Kutta's solver.
-=== Limitations ===
+The latter is automatically used when a stochastic white noise term ''rand_norm(0,[amplitude])'' is included as below, but is not available for Runge-Kutta.
-Solvers with **adaptive time stepping**, such as the [[http://en.wikipedia.org/wiki/Runge%E2%80%93Kutta%E2%80%93Fehlberg_method|Runge-Kutta-Fehlberg]] method, are not available. Currently, we use fixed time stepping methods, because this greatly simplifies temporal scheduling of updates for automated model integration. Incorporation of adaptive time stepping is planned for a future release, though (see ODEint below).
+<code xml>
+ <DiffEqn solver="heun" time-step="0.01" symbol-ref="X">
+   <Expression> rand_norm(0, noise) </Expression>
+ </DiffEqn>
+ <Constant symbol="noise" value="1e-3"/>
+</code>
-Although these implemented explicit solvers are general and flexible, they are not applicable to **stiff systems**. [[http://en.wikipedia.org/wiki/Stiff_equation|Stiff systems]] are ODE systems that can change so rapidly that explicit solvers will result in numerical instability, unless the time step is extremely small. This situation may occur in systems where very large and small values are multiplied.
+=== Fixed time stepping ===
-=== Planned: ODEint integration ===
+Solvers with adaptive time stepping, such as the [[http://en.wikipedia.org/wiki/Runge%E2%80%93Kutta%E2%80%93Fehlberg_method|Runge-Kutta-Fehlberg]] method, are not available. Currently, we use fixed time stepping methods, because this greatly simplifies temporal scheduling of updates for automated model integration.
-Currently, Morpheus implements its own solvers. This was chosen because of the requirements of
-  * parsing of text-entered math expressions using [[http://muparser.beltoforion.de/|muparser]], and
-  * control over precise scheduling of updates.
-However, we are planning to convert to the use of the extremely flexible numerical solver package [[http://headmyshoulder.github.com/odeint-v2/|ODEint]] that will soon be integrated into the well-known [[http://www.boost.org/doc/libs/1_53_0/libs/numeric/odeint/doc/html/index.html|boost library]].
-This will extend the available methods for numerical integration of ODE solvers. For instance, adaptive time stepping solvers will become available. Implicit solvers, to solve stiff systems, may also become available (but will require the specification of the Jacobian).
+=== Stiff systems ===
+Although the implemented explicit solvers are general and flexible, they are not applicable to stiff systems. [[http://en.wikipedia.org/wiki/Stiff_equation|Stiff systems]] are ODE systems that can change so rapidly that explicit solvers will result in numerical instability, unless the time step is extremely small. This situation may occur in systems where very large and small values are multiplied.
 ===== Lattice =====
+==== Lattice structure ====
-== Lattice structure ==
 Morpheus is a lattice-based simulation platform. This means that the spatial models are discretized on a lattice.
@@ Line 67: / Line 44: @@
   * **cubic** 3D (orthogonal) lattice
-== Membrane Properties ==
+==== Boundary conditions ====
+See description in [[documentation:faq#Modeling|FAQ]]
+==== Membrane Properties ====
 For ''MembraneProperties'', properties that are resolved on the surface of cells, Morpheus uses a special lattices with polar coordinate system
@@ Line 74: / Line 55: @@
-== Boundary conditions ==
-See description in [[documentation:faq#Modeling|FAQ]]
 ===== Diffusion =====
-== Method of lines ==
+=== Method of lines ===
 Partial differential equations (PDEs) are numerically approximated by separating the reaction and diffusion steps using the [[http://www.scholarpedia.org/article/Method_of_lines|method of lines]]. This method discretizes the PDE into a system of coupled ODEs. These ODEs are then solved using the numerical methods mentioned above.
-== Diffusion equation ==
+=== Diffusion equation ===
-For diffusion, Morpheus uses the simple and general forward Euler scheme. The time step $\delta t$ is automatically adjusted according to the [[http://en.wikipedia.org/wiki/Courant%E2%80%93Friedrichs%E2%80%93Lewy_condition|CFL condition]] to guarantuee numerical stability.
+For diffusion, Morpheus uses the simple and general forward Euler scheme. The time step $\delta t$ is automatically adjusted according to the [[http://en.wikipedia.org/wiki/Courant%E2%80%93Friedrichs%E2%80%93Lewy_condition|CFL condition]] to guarantuee numerical stability. Alignment of multidimensional lattices to 1D memory (using [[http://www.cplusplus.com/reference/valarray/|valarrays]]) results in highly efficient implementation of diffusion.
-Alignment of multidimensional lattices to 1D memory (due to use of [[http://www.cplusplus.com/reference/valarray/|valarrays]]) results in a high computational efficiency of the implementation of diffusion.
 The unconditionally stable method of [[http://en.wikipedia.org/wiki/Alternating_direction_implicit_method|alternate direction implicit (ADI)]] is also implemented (for constant (Dirichlet) boundary conditions), but is currently not used.
-== Transport equation ==
-Higher order derivatives to model transport equations in PDEs are currently being developed and are planned for a future release.
 ===== Motility =====
@@ Line 129: / Line 101: @@
 where $T$ (for 'temperature') modulates the probability of unfavorable updates to be accepted and can be taken to represent local protrusions/retractions of the cell membrane. The parameter $Y$ (for 'yield') is sometimes used to avoid oscillations with energy-neutral updates. This can be said to represent cytoskeletal resistance to membrane fluctuations.
-=== Random number generators (RNG) ===
+===== Random numbers =====
-By default, Morpheus uses the [[http://en.wikipedia.org/wiki/Mersenne_twister|Mersenne Twister 19937]] pseudo-random number generator included in the CPP GNU compiler (TR1). Alternatively, the [[http://www.boost.org/doc/libs/1_53_0/doc/html/boost_random.html|Boost RNG]] can be used (specified in CMake options).
-**Note**: In multithreaded simulations, each thread gets its own RNG (the random seeds for which are based on the specified seed of the master thread RNG). Therefore, to reproduce simulation results, not only the random seed needs to be specified (''Time/Random/seed''), but also the same number of threads (''Settings -> Local-> threads'').
-===== Model integration =====
-To be documented.
-==== Symbolic references and spatial mapping ====
-- intermodel variable referencing
-- symbols for variables have metadata with their spatiotemporal context (cell property, pde layer etc.)
-- when used in expressions, associated mapping is used
-- in cases of ambiguity, ''Reporter'' plugin should be used to explicitly specify the mapping.
-- Example: autocrine chemotaxis
-==== Time scheduling ====
-The time scheduler takes care (i) to evolve numerical schemes in time, (ii) to schedule and execute spatial data mappings, and (iii) to run event-based schemes, i.e. schemes which are run in certain time intervals. In order to combine different schemes in a single scheduler we exploit the method of fractional time steps. The basis is for our automatic scheduling is extensive knowledge of the data dependencies of the schemes and what kind of updated data they provide. This information is represented as a symbolic dependency tree based on the expressions, input and output symbols defined for the schemes.
-We envisage the following criteria for the design of our scheduler implementation.
-  * Time stepping for all schemes shall be automatically adjusted, as far as possible, to the maximum permitted time step.
-  * In addition, time stepping can be overridden from in the MDL, allowing for user guided step sizes.
-  * The order of the specification of the schemes in the MDL shall not matter.
-  * The sequential order of updates within a temporal step shall be determined by the symbolic interdependency tree extracted from the schemes.
-  * Tightly coupled systems, often bearing circular dependencies, have to be defined in a **System** tag to be updated jointly.
-A robust automatic scheduling methods necessarily needs reliable information about the internal limits of numerical schemes and its external dependencies. External dependencies are extracted as a dependency tree. Internal time step limits are reported by the schemes and can be adoptive in time.
-Solving Reaction-Diffusion Systems, for example, using a finite difference scheme and operator splitting allows us to schedule the diffusion solver depending on the CFL condition and running the reaction part independently.
-=== Schematic Representation of the Time Scheduler ===
+By default, Morpheus uses the [[http://en.wikipedia.org/wiki/Mersenne_twister|Mersenne Twister 19937]] pseudo-random number generator included in the Cpp GNU compiler (TR1). Alternatively, the [[http://www.boost.org/doc/libs/1_53_0/doc/html/boost_random.html|Boost RNG]] can be used (specified in CMake options).
-== Initialisation: ==
+**Note**: In multithreaded simulations, each thread gets its own RNG (the random seeds for which are based on the specified seed of the master thread RNG). Therefore, to reproduce simulation results, not only the random seed needs to be specified (''Time/RandomSeed''), but also the same number of threads (''Settings -> Local-> threads'').
-  - Adjusting time steps:
-    * Continuous Time Solvers: Ensure numerical stability and .
-    * Mappers: Ensuring updated data is available as needed, but not computed more often than necessary. We let the time step size depend on the time steps of the downstream dependency tree (e.g a spatial Reporter shall run as often as it's output is needed by another scheme), and on stability criteria of the numerical schemes (e.g. CFL for Diffusion).
-  - Sorting of schemes to be updated sequentially: The order is determined by the dependency tree. Circular dependencies cannot be sorted unambiguously and thus are rejected.
-  - Initialisation of initial time state (e.g. mappings)
-== Main Loop: 3 Phase Time Stepper: ==
-  - ''Phase I:'' Synchronous Time Evolution Schemes. The schemes are executed sequentially or in parallel, but the results are buffered as intermediates and only applied at the very end of that phase, such that any scheme exclusively depends on the previous time step solutions. Tightly coupled systems, defined in a **System** tag, are evolved by a system solver.
-  - Time Step Progression
-  - ''Phase II:'' Sequentially Updated Schemes (Mappers, Events),  depending on data that has already been updated.
-  - ''Phase III:'' Output generation in Analysis plug-ins. Can be performed in any order, just because there is nor interdependency.
-  - Checkpointing of simulation state.