Package: gillespy2
GillesPy2 is a Python 3 package for stochastic simulation of biochemical systems.  It offers an object-oriented approach for creating mathematical models of biological systems, as well as a variety of methods for performing time simulation of those models.  The methods include theGillespie direct method (SSA), several variant stochastic simulation methods includingtau-Leaping, and numerical integration of ODEs.  The solvers support a variety of user environments, with optimized code for C++, andNumPy.  GillesPy2 also supportsSBML.PLEASE REGISTER AS A USER, so that we can prove GillesPy2 has many users when we seek funding to support development. GillesPy2 is part of theStochSSproject.Table of contentsTable of contentsInstallationUsing PyPIUsing the source code repositoryUsageSimple example to illustrate the use of GillesPy2Getting helpContributingLicenseAuthors and historyAcknowledgmentsInstallationGillesPy2 can be installed on your computer using different methods, as described below.Using PyPIOnLinux,macOS, andWindowsoperating systems, you should be able to install GillesPy2 withpip. Please review the official pipdocumentationfor installation instructions and additional information.Then, to install GillesPy2 from the Python package repository, run the following command:python3-mpipinstallgillespy2--user--upgradeUsing the source code repositoryAs an alternative to getting it from PyPI, you can instructpipto install GillesPy2 directly from the GitHub repository:python3-mpipinstallhttps://github.com/StochSS/GillesPy2/archive/main.zip--user--upgradeAs a final alternative, you can first usegitto clone a copy of the GillesPy2 source tree from the GitHub repository to your local computer disk, and then install GillesPy2 using that copy:gitclonehttps://github.com/StochSS/GillesPy2.gitcdGillesPy2
python3-mpipinstall.--user--upgradeNOTE:to import/export SMBL, libSBML must be installed.  It is not installed by default with GillesPy2.  To include libSBML in the installation of GillesPy2 usepip install gillespy2[sbml].  If GillesPy2 is already installed usepip install python_libSBML.UsageGillesPy2 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 GillesPy2 are:Create aGillesPy2.Modelcontaining molecular species, parameters, and reactions (or import it from anSBMLfile)Invoke the model's.run()method.Therun()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 GillesPy2, please see theGetting StartedJupyter notebook contained in theexamplessubdirectory.Simple example to illustrate the use of GillesPy2Dimerizationis a process in which two molecules of some molecular species (known as a "monomer" in this situation – let's call it "M" for short) come together to create a new molecule (call it "D"), but do so in a way that is reversible, meaning the combined structure can also decay or dissociate back into "M".  A simple model of the dimerization process represents it as two reactions: a reaction in which one molecule of "M" reacts with another molecule of "M" to form one new molecule ("D"), and another reaction in which a molecule of "D" breaks apart into two molecules of "M".  In terms of biochemical reactions, it looks like this (wherekcandkdrepresent the rate constants for creation and dissociation of the dimer, respectively;Mrepresents the number of molecules of "M"; andDis the number of molecules of "D"):kc2 M⟷DkdIn GillesPy2, a model is expressed as an object.  Components, such as the reactions, molecular species, and characteristics such as the time span for simulation, are all defined within the model.  The following Python code represents our dimerization model using GillesPy2's facility:defcreate_dimerization(parameter_values=None):# First call the gillespy2.Model initializer.model=gillespy2.Model(name='Dimerization')# Define parameters for the rates of creation and dissociation.k_c=gillespy2.Parameter(name='k_c',expression=0.005)k_d=gillespy2.Parameter(name='k_d',expression=0.08)model.add_parameter([k_c,k_d])# Define variables for the molecular species representing M and D.m=gillespy2.Species(name='monomer',initial_value=30)d=gillespy2.Species(name='dimer',initial_value=0)model.add_species([m,d])# 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.r_c=gillespy2.Reaction(name="r_creation",rate=k_c,reactants={m:2},products={d:1})r_d=gillespy2.Reaction(name="r_dissociation",rate=k_d,reactants={d:1},products={m:2})model.add_reaction([r_c,r_d])# Set the timespan for the simulation.tspan=gillespy2.TimeSpan.linspace(t=100,num_points=101)model.timespan(tspan)returnmodelGiven 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 10 times to produce 10 sample trajectories:model=create_dimerization()results=model.run(number_of_trajectories=10)The results are then stored in a classResultsobject for single trajectory or for multiple trajectories.  Results can be plotted with matplotlib usingplot()or in plotly (offline) usingplotplotly().  For additional plotting options such as plotting from a selection of species, or statistical plotting, please see the documentation.:results.plot()Alternatively, the results object inherits python-builtinUserDictfor single trajectories, andUserListfor multiple trajectories.  Results can be plotted easily using any plotting library such as matplotlib as shown below:forindexinrange(0,10):trajectory=results[index]plt.plot(trajectory['time'],trajectory['monomer'],'r')plt.plot(trajectory['time'],trajectory['dimer'],'b')With a few additional Python matplotlib commands to create figure labels and such, we end up with a plot like this:Getting helpGillesPy2'sonline documentationprovides more details about using the software.  If you find any problem with GillesPy2 or the documentation, please report it using theGitHub issue trackerfor this repository.  You can also contact Dr.Brian Drawertdirectly with questions and suggestions.ContributingWe would be happy to receive your help and participation with enhancing GillesPy2!  TheUML class diagramandPynsourceUML class modelmay help you familiarize yourself with the existing code. Please follow the guidelines described inCONTRIBUTING.md.New developments happen primarily in thedevelopbranch.  New releases are put in themainbranch.Main BranchDevelop BranchTest CoverageMaintainabilityLicenseGillesPy2 is licensed under the GNU General Public License version 3.  Please see the fileLICENSEfor more information.Authors and historyDr. Brian DrawertDr. Kevin SanftGhilman BrockEliot DixonDalton NickersonSean MatthewMatthew GeigerKassidy HallW.R. JacksonSamuel HodgesEmma WeisgerberAdrien CoulierMike HuckaFredrik WredePrashant SinghBryan RumseyMason KidwellJesse ReeveFin CarterEthan GreenJosh CooperMatthew DippelJoshua Fisher-CaudillAcknowledgmentsThis work has been funded by National Institutes of Health (NIH) NIBIB Award No. 2R01EB014877-04A1.GillesPy2 uses numerous open-source packages, without which it would have been effectively impossible to develop this software with the resources we had.  We want to acknowledge this debt.  In alphabetical order, the packages are:Jupyter– web application for creating documents containing code, visualizations and narrative textlibSBML– a library for reading, writing, and manipulating SBML contentlxml– an XML parsing library for PythonMatplotLib– Python plotting libraryPlotly– Graphing library for making interactive, publication-quality graphsNumpy– the fundamental package for scientific computing with PythonScipy– Python-based ecosystem of open-source software for mathematics, science, and engineeringFinally, we are grateful for institutional resources made available by theUniversity of North Carolina at Asheville, theUniversity of California at Santa Barbara,Uppsala University, and theCalifornia Institute of Technology.