SpatialPy

<p align="left"> <img src="https://raw.githubusercontent.com/StochSS/SpatialPy/main/.graphics/SpatialPy_logo.png"> </p>

SpatialPy is a Python 3 package for simulation of spatial deterministic/stochastic reaction-diffusion-advection problems embedded in Lagrangian reference frame particle based fluid dynamics domain

This package is intended to replace the PyURDME software https://github.com/pyurdme/pyurdme and will feature both a NSM solver for RDME simulation on static domains and a sSSA-SDPD particle based fluid dynamics solver as described in the publication "A hybrid smoothed dissipative particle dynamics (SDPD) spatial stochastic simulation algorithm (sSSA) for advection–diffusion–reaction problems" by Drawert, Jacob, Li, Yi, Petzold https://www.sciencedirect.com/science/article/pii/S0021999118307101

<table><tr><td><b> <img width="20%" align="right" src="https://raw.githubusercontent.com/SpatialPy/SpatialPy/main/.graphics/stochss-logo.png"> <a href="https://docs.google.com/forms/d/12tAH4f8CJ-3F-lK44Q9uQHFio_mGoK0oY829q5lD7i4/viewform">PLEASE REGISTER AS A USER</a>, so that we can prove SpatialPy has many users when we seek funding to support development. SpatialPy is part of the <a href="http://www.stochss.org">StochSS</a> project. </td></tr></table>

Table of contents

• Table of contents
• Installation
  • Using PyPI
  • Using the source code repository
• Usage
  • Simple example to illustrate the use of SpatialPy

<!-- - [_Docker environment_](#docker-environment) - [_Debugging_](#debugging) - [_Profiling_](#profiling) -->

• Getting help
• Contributing
• License
• Authors and history
• Acknowledgments

Installation

SpatialPy can be installed on your computer using different methods, as described below.

Using PyPI

On Linux, macOS, and Windows operating systems, you should be able to install SpatialPy with pip. Please review the official pip documentation for installation instructions and additional information.

Then, to install SpatialPy from the Python package repository, run the following command:

python3 -m pip install spatialpy --user --upgrade

Using the source code repository

As an alternative to getting it from PyPI, you can instruct pip to install SpatialPy directly from the GitHub repository:

python3 -m pip install https://github.com/StochSS/SpatialPy/archive/main.zip --user --upgrade

As a final alternative, you can first use git to clone a copy of the SpatialPy source tree from the GitHub repository to your local computer disk, and then install SpatialPy using that copy:

git clone https://github.com/StochSS/SpatialPy.git
cd SpatialPy
python3 -m pip install  .  --user --upgrade

Usage

SpatialPy provides simple object-oriented abstractions for defining a model of a biochemical system and simulating that model using efficient stochastic simulation algorithms. The basic steps to use SpatialPy are:

1. Create a SpatialPy.Model containing molecular species, parameters, and reactions.
2. Invoke the model's .run() method.

The run() method can be customized using keyword arguments to select different solvers, random seed, data return type and more. For more detailed examples on how to use SpatialPy, please see the Jupyter notebooks contained in the examples subdirectory.

Simple example to illustrate the use of SpatialPy

In SpatialPy, a model is expressed as an object. Components, such as the domains, reactions, biochemical species, and characteristics such as the time span for simulation, are all defined within the model. The following Python code represents our spatial birth death model using SpatialPy's facility:

def create_birth_death(parameter_values=None):
    # First call the gillespy2.Model initializer.
    model = spatialpy.Model(name='Spatial Birth-Death')
    
    # Define Domain Type IDs as constants of the Model
    model.HABITAT = "Habitat"

    # Define domain points and attributes of a regional space for simulation.
    domain = spatialpy.Domain.create_2D_domain(
        xlim=(0, 1), ylim=(0, 1), numx=10, numy=10, type_id=model.HABITAT, fixed=True
    )
    model.add_domain(domain)

    # Define variables for the biochemical species representing Rabbits.
    Rabbits = spatialpy.Species(name='Rabbits', diffusion_coefficient=0.1)
    model.add_species(Rabbits)

    # Scatter the initial condition for Rabbits randomly over all types.
    init_rabbit_pop = spatialpy.ScatterInitialCondition(species='Rabbits', count=100)
    model.add_initial_condition(init_rabbit_pop)

    # Define parameters for the rates of creation and destruction.
    kb = spatialpy.Parameter(name='k_birth', expression=10)
    kd = spatialpy.Parameter(name='k_death', expression=0.1)
    model.add_parameter([kb, kd])

    # Define reactions channels which cause the system to change over time.
    # The list of reactants and products for a Reaction object are each a
    # Python dictionary in which the dictionary keys are Species objects
    # and the values are stoichiometries of the species in the reaction.
    birth = spatialpy.Reaction(name='birth', reactants={}, products={"Rabbits":1}, rate="k_birth")
    death = spatialpy.Reaction(name='death', reactants={"Rabbits":1}, products={}, rate="k_death")
    model.add_reaction([birth, death])

    # Set the timespan of the simulation.
    tspan = spatialpy.TimeSpan.linspace(t=10, num_points=11, timestep_size=1)
    model.timespan(tspan)
    return model

Given the model creation function above, the model can be simulated by first instantiating the model object, and then invoking the run() method on the object. The following code will run the model once to produce a sample trajectory:

model = create_birth_death()
results = model.run()

The results are then stored in a class Results object for single trajectory or for multiple trajectories. Results can be plotted with plotly (offline) using plot_species() or in matplotlib using plot_species(use_matplotlib=True). For additional plotting options such as plotting from a selection of species, or statistical plotting, please see the documentation.:

results.plot_species(species='Rabbits', t_val=10, use_matplotlib=True)

<p align="center"> <img width="500px" src="https://raw.githubusercontent.com/StochSS/SpatialPy/main/.graphics/birth-death-example-plot.png"> </p> <!-- ### Docker environment (DOES NOT WORK) You can use Docker to create a repeatable environment for developing and debugging SpatialPy. The supplied Dockerfile starts a jupyter server with SpatialPy dependencies installed. If you have Docker Compose: `docker-compose build && docker-compose up` Otherwise: ```bash docker build -t spatialpy:latest . docker run -v ./:/home/jovyan/spatialpy -v ./tmp:/tmp -p 8888:8888 -p 5000:5000 ``` The SpatialPy repo is mounted into /home/jovyan so you can import it in the usual way for development (see examples). Any changes you make to your local codebase are reflected in the docker container. Note that you DO NOT need to restart the docker container or even re-import spatialpy to see source changes take effect in jupyter notebooks. The `/tmp` directory is also mounted for easy access to build and result directories. ### Debugging In order to compile the solver binary for use by the debugger, run `solver.compile()` with `debug=True`. This will inject the `-g` flag into the `gcc` command that compiles the solver, enabling gdb debug information. You can invoke `solver.run_debugger()` anytime after you instantiate a solver in Python to start up a new session of gdbgui. The debugger will be available at http://127.0.0.1:5000. ### Profiling To enable profiling, both `solver.compile()` and `solver.run()` need to be invoked with `profile=True`. If you don't run `solver.compile()` explicitly, invoking `solver.run()` with `profile=True` will run `compile()` correctly for you. -->

Getting help

SpatialPy's online documentation provides more details about using the software. If you find any problem with SpatialPy or the documentation, please report it using the GitHub issue tracker for this repository. You can also contact Dr. Brian Drawert directly with questions and suggestions.

Contributing

We would be happy to receive your help and participation with enhancing SpatialPy! Please follow the guidelines described in CONTRIBUTING.md.

New developments happen primarily in the develop branch. New releases are put in the main branch.

<p align="center">

| Main Branch | Develop Branch | |:---------------:|:--------------:| | |

License