Skip to main content

Python package for stochastic simulations

Project description

Logo for cayenne

cayenne : Python package for stochastic simulations

Travis Build Status Azure Build Status codecov Updates Documentation Status pypi License Code style: black Gitter chat

Introduction

cayenne is a Python package for stochastic simulations. It offers a simple API to define models, perform stochastic simulations with them and visualize the results in a convenient manner.

Currently under active development in the develop branch.

Install

Install with pip:

$ pip install cayenne

Documentation

Usage

A short summary follows, but a more detailed tutorial can be found here. You can define a model as a Python string (or a text file, see docs). The format of this string is loosely based on the excellent antimony library, which is used behind the scenes by cayenne.

from cayenne.simulation import Simulation
model_str = """
        const compartment comp1;
        comp1 = 1.0; # volume of compartment

        r1: A => B; k1;
        r2: B => C; k2;

        k1 = 0.11;
        k2 = 0.1;
        chem_flag = false;

        A = 100;
        B = 0;
        C = 0;
    """
sim = Simulation.load_model(model_str, "ModelString")
# Run the simulation
sim.simulate(max_t=40, max_iter=1000, n_rep=10)
sim.plot()

Plot of species A, B and C

Change simulation algorithm

You can change the algorithm used to perform the simulation by changing the algorithm parameter (one of "direct", "tau_leaping" or "tau_adaptive")

sim.simulate(max_t=150, max_iter=1000, n_rep=10, algorithm="tau_leaping")

Our benchmarks are summarized below, and show direct to be a good starting point. tau_leaping offers greater speed but needs specification and tuning of the tau hyperparameter. The tau_adaptive is less accurate and a work in progress.

Run simulations in parallel

You can run the simulations on multiple cores by specifying the n_procs parameter

sim.simulate(max_t=150, max_iter=1000, n_rep=10, n_procs=4)

Accessing simulation results

You can access all the results or the results for a specific list of species

# Get all the results
results = sim.results
# Get results only for one or more species
results.get_species(["A", "C"])

You can also access the final states of all the simulation runs by

# Get results at the simulation endpoints
final_times, final_states = results.final

Additionally, you can access the state a particular time point of interest $t$. cayenne will interpolate the value from nearby time points to give an accurate estimate.

# Get results at timepoint "t"
t = 10.0
states = results.get_state(t) # returns a list of numpy arrays

Benchmarks

direct tau_leaping tau_adaptive
cayenne :heavy_check_mark: Most accurate yet :heavy_check_mark: Very fast but may need manual tuning Less accurate than GillespieSSA's version
Tellurium :exclamation: Inaccurate for 2nd order N/A N/A
GillespieSSA Very slow :exclamation: Inaccurate for initial zero counts :exclamation: Inaccurate for initial zero counts
BioSimulator.jl :exclamation: Inaccurate interpolation :exclamation: Inaccurate for initial zero counts :exclamation: Inaccurate for initial zero counts

License

Copyright (c) 2018-2020, Dileep Kishore, Srikiran Chandrasekaran. Released under: Apache Software License 2.0

Credits

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cayenne, version 1.0.3
Filename, size File type Python version Upload date Hashes
Filename, size cayenne-1.0.3.tar.gz (1.1 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page