spatial-model-editor / spatial-model-editor

Spatial bio-chemical reaction model editor and simulator

Spatial Model Editor

A GUI editor to create and edit spatial SBML models of bio-chemical reactions and simulate them using the dune-copasi solver for reaction-diffusion systems.

To get started, download and run the GUI for your operating system

Linux	MacOS Arm64	MacOS Intel	Windows

Or take a look at our website or the documentation

Pre-release preview binaries are also available which are built from the main branch and can be used for testing new features before the next release:

• Linux pre-release
• MacOS Arm64 pre-release
• MacOS Intel pre-release
• Windows pre-release

Note: on linux some additional system libraries are required that may not be installed by default. To install them:

• Fedora/RHEL/CentOS: sudo yum install xcb-util-image xcb-util-keysyms xcb-util-renderutil xcb-util-wm

Contributing

Bug reports and feature requests are very welcome, as are fixes or improvements to the documentation (to edit a page in the documentation, click the 'Edit on GitHub' button in the top right).

If you are interested in contributing code, please see the contributing guidelines.

Dependencies

Spatial Model Editor makes use of the following open source libraries:

• dune-copasi - license: GPL2 + runtime exception

• libSBML - license: LGPL

• Qt - license: LGPL

• QCustomPlot - license: GPL

• spdlog - license: MIT

• fmt - license: MIT

• SymEngine - license: MIT

• LLVM Core - license: Apache 2.0 License with LLVM exceptions

• GNU Multiple Precision Arithmetic Library - license: LGPL

• GNU MPFR - license: LGPL

• Computational Geometry Algorithms Library - license: GPL

• Boost - license: boost

• libTIFF - license: MIT

• Expat - license: MIT

• oneTBB - license: Apache-2.0

• Open Source Computer Vision Library - license: Apache-2.0

• nanobind - license: BSD-style

• Catch2 - license: BSL-1.0

• Cereal - license: BSD

• zlib - license: zlib

• bzip2 - license: BSD-style

• pagmo - license: GPL

• zipper - license: MIT

• LibCombine - license: BSD

• VTK - license: BSD

• scotch - license: CeCILL-C

Licensing Note

The source code in this repository is released under the MIT license, which is a permissive GPL-compatible license.

The open source libraries that it uses are either also released under a permissive GPL-compatible license, or under a GPL license. As described in the gpl-faq, this means that the work as a whole is then licensed under the GPL.

spatial-model-editor's Issues

analytic initial conditions

should add support for analytic expressions for initial conditions

• look at how to do this correctly in SBML - initialAssignment?
• make sure it is compatible with the existing SampledField initialAssignment
• extend existing SampledField initialAssignment to support any analytic expression involving the SampledField, currently only support assignment
• already supported in DUNE, just need to write expression in ini file using x, y

QCA Net

investigate integration with QCA Net image segmentation code

• https://github.com/funalab/QCANet
• (see also unet)

sbml initialAssignment vs initialConcentration

• if a spatial species is given a spatial initial concentration, it is implemented as an initialAssignment in sbml, which takes precedence over the initialConcentration scalar
• if a constant initialConcentration is then set, this initialAssignment is not removed from sbml, so continues to take precedence

todo: when constant initialConcentration is set, check for and if found remove spatial concentration entries:

• initialAssignment
• spatialSymbolReference
• sampledField

v0.5.0: on windows simulation with DUNE crashes

• however running from command line as `spatial-model-editor.exe > output.txt' works fine
• on windows, by default a GUI app has no console output
• dune-logging seems to redirect std::cout, and this might be causing the crash

todo

• try to stop dune-logging from redirecting std::cout

DUNE integration: separate binary & input/output files

• integrate with https://gitlab.dune-project.org/santiago.ospina/dune-copasi
• output generated PDE and geometry in a format that can be compiled and then solved by DUNE

sampledField: (0,0) location & ordering of values

The sampledField used to define the geometry in SBML is a list of ints, one for each pixel value.

To ensure consistency with other simulators, two things need to be defined in the SBML so that the geometry can be unambiguously interpreted:

• the order of the pixels in the list (e.g. (x=0,y=0), (x=1,y=0), ... )
• the orientation of the axes, e.g. (x=0,y=0) is the bottom-left corner of the image

For example spatialsimulator seems to assume that (x=0,y=0) is the top-left corner of the image, as it flips the y-axis when importing a sampledFieldGeometry in this line:
https://github.com/spatialsimulator/Spatial_Simulator/blob/4204dd078055ca3f53db539754a3593605a1f3c3/spatialsimulator.cpp#L361

use symengine instead of exprtk

• we are using symengine to parse & differentiate expressions for DUNE
• could also use it to evaluate them numerically for the GUI simulations: https://github.com/symengine/symengine/blob/master/symengine/tests/eval/test_lambda_double.cpp
• should compare the performance of this to the current exprtk method: if similar, can remove exprtk dependency and use symengine.
• symengine also has LLVM support which might be interesting in the future

implicit solver

GUI currently has a simple built-in PDE solver based on pixel geometry & explicit Euler integration in time. At some point we could extend this to implicit Euler:

• a species i at point x depends on
  • reactions: all other species j defined at x
  • diffusion: species i at the four nearest-neighbours of x

So Jacobian for resulting Newton solve is sparse: 4 + num_species non-zero elements per row, so don't need to explicitly construct the matrix. Can define operator similar to existing ones for reactions & diffusion that constructs RHS of Jacobian acting on a vector (using SymEngine+LLVM), then solve each Newton step using an iterative matrix-free solver, e.g.

• https://eigen.tuxfamily.org/dox/group__MatrixfreeSolverExample.html

Currently we have slightly non-local reaction terms from the membranes, but if we implement membranes as explicit compartments for DUNE anyway we can do the same here, and then all reactions are strictly local. NB would probably also need to have diffusion of same species occur across boundaries as in DUNE.

Edit SBML model within GUI

• currently expect user to provide SBML model, then we augment it with spatial info
• would be nice to also allow user to edit model directly, e.g.
  • add species
  • add reactions
  • add compartments
  • etc
• may be best to do this by integrating into COPASI, rather than re-implementing this functionality

import geometry from bitmap

build system: use static libraries

to reduce build time & allow enabling of more compiler warnings, statically build and link the following (as is done already for libsbml) instead of keeping them in the source tree and building them with every compile:

• spdlog
• catch2
• qcustomplot (resolved by #42)

DUNE integration: integrated into GUI as static library

• integrate https://gitlab.dune-project.org/santiago.ospina/dune-copasi into GUI executable
• solve PDEs at run-time using DUNE wihout re-compiling

ModelView for Qt Widgets

• currently storing copy of data in Widgets, e.g. QTreeWidget
• when user edits data, have to synchronise it manually
• be nicer to use model/view e.g. QTreeView and a model for the data
• ideally implement as a wrapper class between the widgets and the underlying SBML model, so a change in a widget is directly translated to the SBML model

linux deployment:

• static libsbml library
  • static Qt5 libraries
  • standalone GUI executable

cellDesigner plugin

investigate providing a cellDesigner plugin to integrate the GUI

done for SpatialSimulator here:

• https://github.com/spatialsimulator/Spatial_Simulator_plugin

constant or boundaryCondition species

• if a species is constant or a boundaryCondition without a RateRule then it is not updated during the simulation
  • if it is non-spatial, it can be treated as a scalar constant in the simulation
  • if it has a spatial dependence, it should be treated as a field, but not updated in the simulation

File formats

Need to be able to import/export various things

• spatial model: including spatial geometry and initial concentrations
  • SBML file with spatial extension
• gmsh: geo and msh files to use for simulation
• dune ini file for simulation
• simulation output: vtk file?

This will evolve as dune integration progresses. For now, try to put everything needed to describe the model in the SBML file, deal with the rest later.

xitoSBML

investigate possible integration with XitoSBML:

• https://github.com/spatialsimulator/XitoSBML
• imageJ plugin that creates a spatialSBML model from segmented images

reserved variable names in DUNE ini file

In the DUNE ini file, diffusion "constant" & initial reactions can be all be functions of space in ini file.

This means that x, y and also pi and dim are reserved and should not be used in the equations in the DUNE ini file.

All constants have already been substituted at this point, so the only variables left in the ini file expressions are the species names themselves.

todo: check when generating DUNE ini file that species names are not one of the following:

• x
• y
• pi
• dim

DUNE visualization

we currently have a simple & fast visualization of species concentrations from DUNE:

• average over the three corner values for each triangle
• set the entire triangle to this average value

two better (but slower) alternatives to implement:

• linear interpolation
  • find bounding box of each triangle
  • for each pixel, calculate Baryocentric weight
  • if non-negative, calculate concentration using weights
  • see e.g. https://codeplea.com/triangular-interpolation
• generic any-order solution
  • as above to find points inside triangle
  • but then convert each point to local coordinate in DUNE
  • evaluate DUNE function at this local coordinate

import/export spatial SBML models

• currently we can import non-spatial SBML models
• then we augment them with spatial info to generate PDE
• would be nice to convert this into spatial SBML format and support importing/exporting models including the spatial information

Augment SBML model with spatial info within GUI

• given SBML model, gui should allow user to
  • assign compartments to geometry based on image
  • identify membranes between compartments (done automatically by GUI)
  • make a species spatial (implies other species in compartment also spatial?)
  • set diffusion constant of a species
  • import initial concentration from image
  • set the scale of compartment, membrane, model, etc

windows deployment:

• static libsbml library
  • static Qt5 libraries
  • standalone GUI executable

cache dependencies in CI builds

currently statically compile dependencies in:

• https://github.com/lkeegan/llvm-static
• https://github.com/lkeegan/libsbml-static
  then download them when we build spatial-model-editor

this works, but need to keep compiler used in sync: if we change it somewhere we (should) update all to use the same.

could instead build everything in spatial-model-editor CI, but use caching to only rebuild dependencies when their version number changes.

would probably make sense to do this when we switch to using cmake for the build system #46, and could also look at using a package manager such as conan

Meshing

• want to generate 2d mesh from image for DUNE
• look at using http://gmsh.info for this
• look at other (simpler) alternatives?
  • e.g. https://github.com/jhasse/poly2tri seems to be used by Qt for some simple meshing

osx deployment:

• static libsbml library
  • static Qt5 libraries
  • standalone GUI executable

code coverage reports

• generate coverage output as part of CI
• upload result to codecov.io

v0.5.0 on osx simulation with DUNE crashes

• if GUI is ran by opening .dmg then running it (i.e. default) it crashes
• because dmg is read-only, so GUI fails to write grid.msh file to working directory

workaround

• extract the app folder from the dmg first, then it can write the file

possible solutions

• see if dune gmshreader can be altered to take a string instead of a file
• alternatively, directly construct the dune mesh in the GUI and pass this to dune-copasi
• or distribute a tar.gz instead of a disk image: then should be able to write to the file

catch2 unit tests

support RateRules

Instead of specifying reactions, the SBML model can directly specify the ODE for a species in the form of a RateRule.

Support for this needs to be added to the GUI.

SBML test suite

• test simulations for non-spatial ODE models
• can use both internal solver and DUNE solver routines
• http://sbml.org/Software/SBML_Test_Suite

qtest gui tests

scale / dimensions of geometry

As part of #9 we need to set the scale of the geometry / compartment.
In principle this information already exists via the size or volume parameter of each compartment, but for multiple compartments it is unlikely to be consistent with the geometry image.

Several ways to do this consistently:

• user specifies width or height of geometry image in some units
  • area of each compartment then calculated by the GUI
• user specifies area of a compartment in some units
  • geometry dimensions and other compartment areas calculated by GUI

The size parameter often features as part of the reaction terms, as an implicit conversion between intrinsic/extrinsic units, so care should be taken not to inadvertently change the dynamics by changing this value...

Symbolic Derivatives

• would be nice to have symbolic derivatives to provide analytic Jacobian of reaction terms for Newton solver in DUNE
• investigate https://github.com/symengine/symengine
  • C++ library which implements a subset of SymPy
• check status of this within COPASI

build system: use cmake

curently using qmake as the build system as it is the qt default

be nice to change to cmake because:

• it has better integration with catch2, spdlog, etc libraries
• cmake is more widely used / better supported in general
• qt itself is moving to cmake as the build system for qt6

PDE simulation tests

• compare numerical results to other spatial simulators:
• morpheus
• vcell
• https://github.com/spatialsimulator
• http://www.smoldyn.org

ODE simulation tests

• single-pixel comp geometry is equivalent to non-spatial model
  • set up some simple test models
  • run same models in COPASI
  • have tests that numerically compare results

example models

would be good to extend the example models with:

• a simple model which can be analytically solved
• a model with many & complicated reactions for profiling the solver
• a model which can also be simulated using morpheus/virtual cell/etc
• pure diffusion, single compartment: check vs analytic solution & conservation
• pure diffusion, multiple compartments: check vs analytic (small time) solution, conservation of total amount in each compartment, at late times should be uniform within each compartment
• the same model with multiple resolutions of the same geometry, to look at discretization errors

debug versions of static libraries

• we statically build various dependencies
• would be nice for debugging purposes to also build debug versions of these with e.g. ASAN enabled

initial conditions -> DUNE

need to add support to provide initial conditions to DUNE as

• 16bit grayscale TIFF
  • this is rescaled by DUNE to doubles in range [0,1]
• analytic function that references the above values

SBML doc contains a SampledField array of doubles, and an initial assignment, so we need to construct a TIFF from the SampledField, rescaling doubles to integers in a suitable range, and using the same rescaling factor in the analytic expression.

Also need to convert from pixel indices to physical points.

SBML doc spatial issues

If we add an initial condition from an image, we need to create in SBML:

• sampled field of concentrations
• spatial reference to this field
• initial assignment which refers to this reference

If we then set a constant initial condition, we should remove the above. In principle the sampled field & spatial ref could be used elsewhere though, especially if we have imported a spatial SBML doc created elsewhere.

Currently adding and removing spatial features will leave behind unused data in the SBML doc.
This is also related to #54.

possible solutions:

• assume we only edit our own spatial models
  • we know what we added, can remove it when no longer used
  • but doesn't work if/when we import & edit spatial SBML from other sources
• reference counting for use of sampled fields, spatial refs, etc
  • more general, but potentially much more complicated/fragile
• maintain full model state ourselves
  • import/export from SBML when loading/saving SBML file
  • but would end up duplicating a lot of existing SBML functionality

reaction math parsing/evaluating

• parse reaction expression
• parse reaction parameters
• inline function calls
• apply units correctly to all parameters
• apply volume factors to species if required (can be conc or numbers depending on flag in sbml file)
• compile expression so it can be numerically evaluated

visualisation of DUNE output

• currently DUNE ouptut -> vtk, which can be viewed with paraview.
• would be nice to directly visualise data in GUI
• can construct from DUNE grid data structure
• see https://gitlab.dune-project.org/pdelab/dune-pdelab-tutorials/blob/master/gridinterface/exercise/solution/grid-exercise1.cc

DUNE interface condition

• DUNE specifies interface condition in terms of the derivative of species concentration w.r.t normal vector of boundary surface

• SBML models instead typically specify a reaction involving species on both sides of boundary

• need to think about how to convert the latter into the former

  • DUNE has access to concentrations on both sides of the boundary, so in principle possible

libfmt is included twice

• dune-logging and spdlog both bundle libfmt
• we should instead add libfmt as a static library
• then make both dune-logging and spdlog to it instead of using their own bundled versions

Modal widget native dialogs

The tests on osx CI hang if a native modal widget is used, for:

• QFileDialog::getOpenFileName
• QFileDialog::getSaveFileName
• QColorDialog::getColor

The solution for now is to pass the DontUseNativeDialog flag to these routines, then it works fine.

Todo: check that this also works (and looks ok) in reality on osx and windows

units

our simulation is 2d, but users will expect quantities and reaction parameters to be in 3d units

• need to decide how to implement this / present this to the user
• should be some consistency checks
• and automatic rescaling where possible
• could say our 2d is a slice of 3d of unit depth
  • (but does the depth change when the units change?)
• SBML doc contains units but they are only cosmetic
• DUNE doesn't care about units

v0.5.0: doesn't run on osx<10.14

• due to C++17 used in dune-logging and dune-copasi, using the system compiler on osx we can only compile if we target osx version >=10.14
• resulting app refuses to run on older osx versions

however

• we statically compile libstdc++, and running the application from the command line on older osx versions actually seems to work fine
• editing Info.plist to change 10.14->10.12 had no effect, but apparently it is cached by the os

todo

• try changing 10.14 -> 10.12 in the Info.plist file in the travis build before making the dmg

sbml isSpatial

• when isSpatial is checked, user can then assign
  • diffusion constant
  • initial spatial concentration
  • etc
• if isSpatial is unchecked, all spatial info above should be removed from SBML document

display geometry