Differences

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

--- documentation:faq [13:43 17.08.2021] – Uncollapse FAQ Diego Jahn
+++ documentation:faq [14:14 17.08.2021] (current) – Moved to GitLab Pages Diego Jahn
@@ Line 10: / Line 10: @@
-==== Software structure ====
-Morpheus is a self-contained application. Internally, it consists of two stand-alone executables:
-  * ''morpheus'': the simulator
-  * ''morpheus-gui'': the graphical user interface (GUI)
-The communication between these stand-alone applications is through XML and XSD files:
-  * The GUI reads an XML Schema description (XSD) file that specifies rules for valid XML models.
-  * The GUI start a simulation job by executing ''morpheus'' with a generated XML model as argument.
-Note that both executable can also be used as stand-alone programs. The simulator ''morpheus'' can also be used as stand-alone program from the command line. And ''morpheus-gui'' may be used to control remote computing resources.
-[{{ :morpheus-sim.png?direct&400 | ''morpheus'' simulator from the command line interface. }}]
-==== Source code ====
-** Source **
-The source code publicly available at [[https://gitlab.com/morpheus.lab/morpheus|GitLab]]
-** Building from source **
-Information on building Morpheus from source can be found [[https://gitlab.com/morpheus.lab/morpheus/blob/master/README.md|here]].
-==== Where can I get help? ====
-** User forum **
-Use the [[forum:users|Morpheus user forum]] to get support from developers and other users.
-** User manual **
-The [[documentation:manual|user manual]] is the primary source of information on usage of Morpheus.
-** Debug mode **
-Run your model in debug mode by select the crashed job in the Job Queue, then right-click and choose ''Debug''.  This requires that you have gdb (Gnu Debugger) installed. \\
-[{{ :faq_debug.png?direct&250 | Run a crashed simulation in ''Debug'' mode, and send us the log file ''gdb.log''.}}]
-==== Developers ====
-Morpheus is developed by Jörn Starruß and [[http://walter.deback.net|Walter de Back]] at the [[http://imc.zih.tu-dresden.de/imc|IMC group]] headed by prof. [[http://imc.zih.tu-dresden.de/imc/index.php?page=members&who=deutsch|Andreas Deutsch]].
-We are part of the [[http://tu-dresden.de/die_tu_dresden/zentrale_einrichtungen/zih|Center for High Performance Computing]] at the [[http://www.tu-dresden.de/en|Technische Universität Dresden]], Germany.
 ===== Modeling =====
-==== Your first model ====
-** Use an example **
-The easiest way to start to create your own models, is to browse the [[examples:examples|Examples]] and use them as templates. The examples can be found under ''File->Examples''.  \\ \\
-** Start from scratch **
-To start from scratch, use ''File->New''. This will generate a [[examples:miscellaneous#minimal_model|minimal valid model]]. Then, check out [[#Editing|how to edit models]].
-** Required and optional model items **
-Each valid ''MorpheusModel'' specifies the following required items: \\
-  * ''Description'': Title and description of model
-  * ''Space'': Lattice size, structure, length scale and boundary conditions
-  * ''Time'': Simulation duration, checkpointing, time scale, and random seed.
-And may be extended with the following optional items: \\
-  * ''CellTypes'': Definition of cell types, their properties and behaviors
-  * ''CPM'': Specific parameters for cellular Potts model
-  * ''PDE'': Specification of reaction-diffusion system
-  * ''CellPopulations'': Specification of cell population and spatial layout
-And can be analyzed using the following optional items: \\
-  * ''Analysis'': Data, analysis and visualization tools
-  * ''ParamSweep'': Batch processing tool (in GUI)
-==== Boundary conditions ====
-** Types of Boundary Conditions **
-Morpheus provides three types of boundary conditions.
-^  Types of BoundaryConditions  ^^^
-^ Name ^ Synonym ^ Meaning ^
-| **Periodic** | Wrap-around | Border states are mapped to states at opposite border. |
-| **Constant** | Dirichlet | Border states have specified constant values. |
-| **Noflux** | Neumann | Derivative at border is zero. |
-These can be specified in ''Space -> Lattice -> BoundaryConditions''. These define the **structure** of the boundaries.
-[{{ :faq_boundarycondition1.png?direct&400 | The structure of the borders is defined in ''Space -> Lattice -> BoundaryConditions''. }}]
-Note that there are six boundaries (''x, -x, y, -y, z, -z''). All need to be specified, expect when periodic boundaries are used (in which case ''x=-x, y=-y, z=-z'').
-** Constant boundary condition **
-To define constant boundaries, select ''constant'' in ''Space -> Lattice -> BoundaryConditions''.
-To specify the **values** the constant boundaries should take, we distinguish between reaction-diffusion models (''PDE'') and cell-based models.
-** Reaction-diffusion models (PDE) **
-When using ''constant'' boundary conditions, values used at the boundary of a reaction-diffusion model can be specified in ''PDE -> Layer -> BoundaryConditions''. Assuming nonzero diffusion, this causes a constant influx (or efflux) from (at) that boundary. The default value is $0.0$.
-[{{ :faq_boundaryconditions_PDE.png?direct&400 | Specify values at boundaries in ''PDE -> Layer -> BoundaryConditions''. }}]
-** Cell-based models **
-A particular ''medium'' cell type can be specified at constant boundaries. First, define a cell type of type ''medium'' under ''CellTypes''. To specify this at the boundary of a cell-based model with ''constant'' boundary conditions, use ''CPM -> BoundaryConditions''.
-[{{ :faq_boundaryconditions_CPM.png?direct&400 | Specify cell types at boundary in ''CPM -> BoundaryConditions''.}}]
-==== Initial conditions ====
-To specify initial conditions, we distinguish between reaction-diffusion models (''PDE'') and cell-based models.
-** Reaction-diffusion models (PDE) **
-To set an initial condition for a species in the reaction-diffusion model, specify it in ''PDE -> Layer -> Initial -> InitPDEExpression -> Expression''.
-Note that you can express the initial condition in terms of the lattice size using the symbols set in ''Space -> Lattice -> Size/symbol'' (here: ''s'') and ''Space -> SpaceSymbol'' (here: ''l'').
-[{{ :faq_initialconditions_PDE.png?direct&600 | Set initial conditions of ''PDE'' using ''InitPDEExpression'' in terms of spatial symbols for lattice size.}}]
-** Cell-based models **
-Initial conditions for a ''Property'' of a ''CellType'' are specified when you define the ''Population'' of cells. Set the initial values using ''CellPopulations -> Population -> InitProperty''.
-[{{ :faq_initialconditions_Cells.png?direct&500 | Set initial condition for cell ''Properties'' using ''InitProperty'' in the ''Population'' definition. }}]
 ==== Random seed ====
@@ Line 155: / Line 30: @@
   * In simulation using multithreading (openMP), each thread gets its own random seed. Therefore, to reproduce exact results, one needs to specify the same random seed as well as the same number of threads.
-==== Time scales ====
-Specifying time scales is important, especially in multiscale models in which dynamics occur at multiple temporal scales.
-In Morpheus, we distinguish three time scales:
-  - Global time: defines the time frame of a simulation.
-  - Monte Carlo time scale: defines updating scheme of cells.
-  - System time scale: defines updating and dynamics of systems of (differential) equations.
-** Global time **
-Each model must specify a **global time** scheme under ''Time'' that runs from ''StartTime'' to ''StopTime''. All other processes are scheduled within this time frame.
-For **dimensionless models**, a sensible choice for the global time scheme would be from $0$ to $1$. For an example, see the [[examples:multiscale#Cell cycle: coupling ODEs to CPM|cell cycle model]] (''File -> Examples -> MultiScale -> CellCycle'').
-Alternatively, for **dimensional models**, time ''units'' can be specified (''msec'', ''sec'', ''min'', ''hours'', ''days'') such that one could define the global time to run from ''20 hours'' to ''7 days''. Default interpretation is 1 sec.
-** Monte Carlo time scale (CPM) **
-The time scale of cellular Potts models can be specified using ''CPM -> MCSDuration''. This defines the interval between Monte Carlo steps, in terms of global time scheme.
-For example, if the global time is defined from $0 \rightarrow 1$, and ''MCSDuration'' is set unitless to $1.0\cdot10^{-2}$, a total of $100$ Monte Carlo steps will be performed during the simulation.
-Alternatively, if the global time is defined with dimenions from $0$ ''hours'' to $1$ ''hours'', and ''MCSDuration'' is set to $1.0$ ''sec'', a total of $3600$ Monte Carlo steps will be performed during the simulation.
-Note that changing the ''MCSDuration'' time scale directly affects the CPM dynamics such as cell motility and cell shape changes. In fact, it will affect all processes under ''CellTypes -> CellType'', **except** the processes defined within ''System''s.
-** System time scale (ODE/PDE) **
-To define the time scale for a ''System'' of (differential) equations, we need to distinguish between:
-  - Numerical updating scheme: how often the equations with the systems are evaluated.
-  - System dynamics: setting the time scale of ODE model dynamics, relative to the global time. \\
-The numerical updating of a system of equations is defined in ''System -> time-step'' (default=$1$), in terms if the global time scheme. This sets the accuracy of the numerical approximation (i.e. it is the $ht$ of the numerical solver), but does not affect the time scale of its dynamics. \\ \\
-To **change the time scale of the dynamics** of simulated ODE model, you can use the ''System -> time-scaling'' attribute. This scales the rates of dynamics, while maintaining the accuracy (by automatically scaling the time-step). For an example, see the [[examples:multiscale#ODEs in CPM cells: Cell cycle and proliferation|multi-scale cell cycle model]] (''File -> Examples -> Multiscale -> CellCycle'').
 ==== Spatial scale ====
@@ Line 202: / Line 41: @@
 Dimensionless space is assumed, unless a unit is specified.
-==== Neighborhoods ====
-** Types of Neighborhoods **
-Two types of neighborhood are used: \\
-  * ''Space -> Lattice -> Neighborhood'': ...
-  * ''CPM -> MetropolisKinetics -> Neighborhood'': ...
-** Order and Distance **
-The number of neighboring nodes to include can be specified in two different units: \\
-  * Distance: All nodes <= this distance are included in the neighborhood.
-  * Order: All nodes of this order are included in the neighborhood.
-** Order **
-The "order" of a neighborhood is a measure of neighborhood size that expands in an alternating way axially and radially.
-In a square lattice:
-  * Order 1: 4-member, axial (von Neumann)
-  * Order 2: 8-member, radial (Moore)
-  * Order 3: 12-member, axial
-  * ...
-[{{ :faq_neighborhood.png?direct&500 | Neighborhood orders 1-4 indicated by numbers around the focal node for a square and hexagonal lattice.}}]
-==== ''Function'' or ''Equation''? ====
-Both are algebraic expressions, however: \\
-  * A ''Function'' defines a ''symbol'', and it calculated whenever this symbol is used.
-  * An ''Equation'' changes the value of a symbol defined elsewhere (''symbol-ref'') and is calculated every ''time-step''. \\ Note: if an ''Equation'' is part of a ''System'', the ''time-step'' of the ''System'' overrules the one defined by the ''Equation'' itself.
-^ ^ Attribute ^ Evaluation ^
-|''Function'' |''symbol''  | Evaluated when symbol is used |
-|''Equation'' |''symbol-ref'' | Evaluated every ''time-step'' (default=1), set result to referred ''Property'' |
 ===== Analysis =====
-==== 2D Visualization (Gnuplot) ====
-Use the ''Gnuplotter''. See the [[examples:examples|Examples]] to learn how to use it.
-==== 3D Visualization (TIFF / VTK) ====
-** 3D visualization **
-To visualize 3D simulations, Morpheus can write TIFF images stacks or VTK files. \\
-These files can be rendered with external software, such as [[http://fiji.sc/wiki/index.php/Fiji|Fiji]] or [[http://www.paraview.org/|Paraview]]. \\
-** Viewing 3D TIFF images with Fiji/ImageJ **
-To export 3D images as TIFF z-stacks, use the ''Analysis -> TiffPlotter'' plugin. \\
-The resulting TIFF images can be opened using the 3D Viewer in [[http://fiji.sc/wiki/index.php/Fiji|Fiji]], an image processing package based on ImageJ (see ''Plugins -> 3D Viewer''). \\
-[{{ :faq_3d_visualization.png?direct&500 | Use ''TiffPlotter'' for 3D, 4D or 5D visualization in Fiji. }}]
-By concatenating TIFF stacks, you can also render 4D (3D+time) or even 5D (3D+time+channels) movies. \\
-** Fiji Macros **
-We provide some simple Fiji macros to generate such 3D images and 4D/5D movies. To install them: \\
-  * Download {{::morpheus_fiji_viewers.zip|morpheus_fiji_viewers.zip}}
-  * Extract contents in Fiji/macros
-    * Mac: Select ''Applications/Fiji.app'', then right-click and select ''Show Package Contents''.
-    * Ubuntu: Default location is ''$HOME/Fiji.app/macros''
-This will install a new toolset in the Fiji interface called ''Morpheus Viewer'' from which the 3D/4D/5D viewers are available. \\
-** Paraview **
-[[http://www.paraview.org/|Paraview]] is an application for visualization of large 3D data sets in VTK format ([[http://www.paraview.org/paraview/resources/software.php|download here]]).
 ==== Data output and visualization ====
@@ Line 443: / Line 211: @@
 =====  GUI =====
-==== Execution mode: ''interactive'', ''local'' or ''remote''? ====
-[{{ :faq_local_interactive.png?direct&400 |Use **interactive** to direct visual output to screen instead of file.}}]
-Simulations can be executed in different **job queues** for different tasks. \\
-Local/interactive jobs are started in local job queue that is handled by Morpheus itself. Remote jobs are submitted over a ''ssh'' connection to the batch queuing system of the high performance computing resource (e.g. LSF).
-** Local / Interactive / Remote **
-Roughly, local mode is the 'normal' mode for simulation, while interactive mode is for rapid testing. \\
-In interactive mode:
-  * Visual output (e.g. Gnuplotter) is directed to an on-screen terminal by overriding the specified terminal.
-  * Stop current interactive job from toolbar button.
-** Remote **
-Remote mode submits a job to the queueing system on a remote high performance computer.
-Remote mode requires password-less ''ssh'' authentication (i.e. using [[http://linux.die.net/man/1/ssh-copy-id|''ssh-copyid'']]). Specify  username/password details under ''File -> Preferences -> Remote''.
-On first use, Morpheus copies a proxy script to the remote computer through which Morpheus communicates with the job scheduling system. Morpheus is shipped with a proxy script for [[http://en.wikipedia.org/wiki/Platform_LSF|LSF]], but this can easily be adapted to other scheduling systems.
-^ Job queue ^ Purpose ^ Behavior ^
-| **Local**  | Normal processing  |  |
-| **Remote** | Remote batch processing  | Submit job to remote queuing system (e.g. LSF) on high performance computing resource. \\ **Note**: Feature not yet available in public version |
-| **Interactive** | Testing mode | Start/Stop simulations from toolbar buttons. \\ Directs visual output to on-screen terminal. \\ Overrides ''Gnuplotter'' terminal to ''wxt'' (Linux), ''aqua'' (Mac) or ''win'' (Windows). |
 ==== FixBoard ====
@@ Line 527: / Line 267: @@
 Remove or rename the file ''morpheus.db.sqlite'' to reset the job archive. Note that this does not remove the simulation results themselves.
-==== Checkpointing (simulation snapshots) ====
-** Checkpointing **
-Storing snapshots of the simulation state during execution is called [[http://en.wikipedia.org/wiki/Application_checkpointing|checkpointing]].
-This allows the user to e.g.:
-  * Restore a simulation
-  * Continue a simulation under different conditions
-  * Use the end-state of a simulation as initial condition of a new simulation \\
-** Enable checkpointing **
-Checkpointing is switched off by default.
-To enable checkpointing, add the item ''Time -> SaveInterval''.
-To set the interval, set the ''Time -> SaveInterval -> value''.
-Special cases:
-  * value = -1: Disable checkpointing
-  * value =  0: Store state only at start and end
-  * value >  0: Store state at specified time interval
-** File format **
-Snapshots are saved in a compressed XML format with the filename ''[Title][Time].xml.gz''.
-** Open saved models **
-Snapshot files ''[Title][Time].xml.gz'' can be opened by double-clicking on them in the GUI.
-From the command line, first unzip the file and then run ''morpheus [Title][Time].xml''
-** Limitations **
-The snapshots store the complete simulation state. However, the values of **PDE Layers are not stored**.
-This is excluded because of (1) the large storage requirements and (2) the required time to write to text file. (In the future, separate binary files will be written for PDE Layeres which can be stored and written more efficiently, but are more difficult to do in a platform independemt fashion.)
-** Restore parameter sweeps **
-Parameter sweeps can also be restored. This restores the parameters and value ranges specified for a particular model.
-This feature requires an opened model that has the same parameters.
-===== Settings =====
-==== Multithreading / Concurrent jobs ====
-  - Number of threads: Used to set number of openMP threads for (in-job parallelization)
-  - Concurrent jobs: number of jobs executed in parallel (between-job parallelization)
-==== Gnuplot path ====
-By default, Morpheus uses the first GnuPlot executable it can find in the PATH environmental variable.
-Optionally, you can overrule this path.
-** Graphical User Interface **
-To use a specific GnuPlot version, specify you gnuplot executable under ''File -> Settings -> Local -> Gnuplot executable''.
-** Command Line Interface **
-To specify a gnuplot executable from the command line, you can use the ''gnuplot-part'' option as command line argument:
-<code bash>
-  morpheus -gnuplot-path [File]
-</code>