Poincare and simbio 1.0.0 are releasing

[olistarosta]

Poincare and simbio 1.0.0 are releasing

Dyscolab is happy to announce the release of poincare and simbio 1.0.0! Poincare is a general purpose dynamical systems simulations python library, and simbio builds on it to provide bindings for chemical reactions networks. They aim to provide a layer to separate model declaration from simulation, making it easy to simulate the same model using different backends, and also provide a series of analysis tools for tasks such as parameter sweeps.
Originally presented in the 2024 paper, version 1.0.0 brings a significant update involving new features and a reworking of internal systems to make it more stable and maintainable. The release also includes new documentation to make it easy to start simulating your own systems or contributing to the project.
As an example we can create and simulate a harmonic oscillator in poincare:

import numpy as np
from poincare import *


class Oscillator(System):
    x: Variable = initial(default=1)  # create variable x with default i.c. 1
    v: Derivative = x.derive(initial=0)  # create derivative for x called v with default i.c. 0
    k: Parameter = assign(default=1)  # create parameter k with default value 1

    eq = v.derive() << -k * x  # equation x'' = -k*x

sim = Simulator(Oscillator)  # create Simulator
sim.solve(save_at=np.linspace(0, 10, 100)).to_dataframe().plot()  # solve and plot

Smaller models can be composed to create more complex ones, so to make coupled oscillators we can write:

class Coupled(System):
    osc_1 = Oscillator()
    osc_2 = Oscillator()  # create two oscillators

    eq_1 = osc_1.v.derive() << -0.1 * (osc_1.x - osc_2.x)
    eq_2 = osc_2.v.derive() << -0.1 * (osc_2.x - osc_1.x) # add interactions between them

sim2 = Simulator(Coupled, backend="numba")  # switch compilation backend to numba
result = sim2.solve(
    save_at=np.linspace(0, 100, 1000), values={Coupled.osc_2.x: 0}
)  # change i.c. for for osc_2.x to 0
result[["osc_1.x", "osc_2.x"]].to_dataframe().plot()

Poincare also has a series of analysis tools, we can easily do a parameter sweep on the spring constant and see how it affects the period:

osc = Oscillations()
result = osc.sweep(
    sim, T_min=0.5, T_max=30,r el_time=10,
    parameter=Oscillator.k,values=np.linspace(1, 10, 10))  # solve at each k in values and find the period
result.sel(quantity="period")["x"].to_dataframe().plot(marker=".", title="period vs. spring constant")

Simbio adds specific bindings for declaring chemical reactions, such as RateLaw and MassAction, as well as pre-made reactions such as Equilibration. It can optionally keep track of volume, allowing for the creation of Species that can represent either concentrations or absolute amounts:

from simbio import *
from simbio.reactions import *
from simbio.core import Volume


class Chemical(Compartment):
    V: Volume = Volume(initial=2)
    A: Species = concentration(default=2)  # declare A as representing concentration
    B: Species = amount(default=3)  # declare B as representing absolute amount

    eq1 = RateLaw(reactants=[2 * A], products=[B], rate_law=0.1)  # 2A -> B at given rate
    eq2 = MassAction(reactants=[2 * A], products=[B], rate=0.1)  # 2A -> B at rate according to the mass action law
    eq3 = Equilibration(A=2 * A, B=B, forward_rate=2, reverse_rate=1)  # 2A <-> B

sim = Simulator(Chemical)  # simulation works the same way as it does poincare
sim.solve(save_at=np.linspace(0, 10, 100)).to_dataframe().plot()

To learn more about poincare or simbio see the their documentation on dyscolab's page or jump directly into poincare's or simbio's intro tutorial; if your interested in the project you can start simulating systems and publish your examples in the show and tell forum or contribute to development on github. Development is still ongoing, so we expect to release more features in the near future including:

• The ability to automatically generate a LaTeX report containing a model's equations variables and parameters, making it easier to debug large system's and maintain consitency between analytic and numerical formulations.
• Stochastic simulations using Gillespie's algorithm, so the same model can be simulated either stochastically or as an ODE by changing a single line of code.
• The ability to import models in the SBML format into simbio, both locally and directly from the BioModels repository.