Package: biosimulators-simularium
Biosimulators_simulariumConverting Biosimulators spatial simulation outputs into a Simularium-compliant format.PLEASE NOTE:If you are using Apple silicon or Windows, you MUST use the Building from Source installation. Currently, smoldyn is only
available on PyPI cleanly on Linux.Installation with Python(PyPI) (Recommended)The easiest way to interact withBiosimulators_simulariumis via the Python Package Index and avirtual environment.poetry use python3.10We recommendinstalling and using Conda:After you have created the environment...conda create -n biosimularium python=3.10conda activate biosimulariumpip install biosimulators-simulariumTo verify successful platform installation...python3import biosimulators_simularium as biosimulariumbiosimularium.__version__should display the most recent version with no errors.Installation (Building from Source) (Preferred)The preferred build-from-source method involves using Python Poetry. Please ensure that this
is globally installed on your machine. The preferred method of installation from source
is through the use of theinstall-deps.shscript that is included at the root of this
repo. Follow the instructions below to install the environment on your machine (mac):git clone https://github.com/biosimulators/biosimulators-simularium.gitcd Biosimulators_simulariumchmod +x ./install.sh./install.shOPTIONAL:poetry shellpython3import biosimulators_simulariumIf there are no errors, you are all set!Installation (Building from Source) (Alternative)BEFORE STARTING: This application uses Smoldyn to generate simulation data. Please install Smoldyn into your local environment. Instructions below use the Mac silicon install and Python 3.10. More information on installing Smoldyn can be foundhereSet up a virtual environment. We recommend using Conda:conda create -n biosimularium  python=3.10conda activate biosimulariumcd {REPO DESTINATION}git clone https://github.com/biosimulators/biosimulators-simularium.gitcd Biosimulators_simulariumpip install -e .FOR MAC ONLY: Download Smoldyn for your Mac (Silicon or Intel):https://www.smoldyn.org/download.htmlcd /path/to/your/download/of/smoldyn-2.72-macsudo -H ./install.shOTHERWISE:pip install smoldynA Jupyter Notebook will soon be available which is based off of the simulariumio tutorial series. This will
give users the ability to have a tool that quickly generates simularium files with the click of a button based
on a valid COMBINE/OMEX archive.Getting-Started Example:Generating a 3d stochastic particle diffusion simulation visualization is as easy as:Defining the filepath to an unpacked directory/archive in which a Smoldyn model resides
and defining the name of simularium file. We also want to save the simularium file in JSON format:frombiosimulators_simulariumimportgenerate_simularium_filearchive_root='biosimulators_simularium/tests/fixtures/archives/MinE'simularium_fn='simulation'is_json=TrueGenerating a simularium file from the model file housed in thearchive_root:generate_simularium_file(working_dir=archive_root,simularium_filename=simularium_fn,use_json=is_json)importosassertos.path.exists(os.path.join(archive_root,simularium_fn)))Here is another, slightly more complex example in which agent parameters such as molecular mass and density are defined:"""Generating a simularium file for the MinE Smoldyn model."""importosfrombiosimulators_simulariumimportgenerate_simularium_file# define the working dir: here we use a dir from the tests library as an example.working_dir='biosimulators_simularium/tests/fixtures/crowding'# define the simularium filepath (using the working dir as root in this case)simularium_fn=os.path.join(working_dir,'simplified-api-output')# define the path to the smoldyn model file which in this case is assumed to be in the working dirmodel_fp=os.path.join(working_dir,'model.txt')# define agent parameters (for this example, we randomly select masses)red_molecular_mass=11004green_molecular_mass=12424# create a parameter mapping that maps simulation species type names to respective density and molecular_massagent_params={'red':{'density':1.0,'molecular_mass':red_molecular_mass,},'green':{'density':1.0,'molecular_mass':green_molecular_mass,}}# generate a simularium file from the given parametersgenerate_simularium_file(working_dir=working_dir,simularium_filename=simularium_fn,agent_params=agent_params,model_fp=model_fp)# test the existence of a simularium filetry:assertos.path.exists(simularium_fn)print(f'{simularium_fn}has been successfully generated.')except:AssertionError('A simularium file could not be generated.')Consider also this MinE simulation where we use the params function to extract parameters of agents from the Smoldyn model file:importosfrombiosimulators_simularium.simulation_dataimportgenerate_agent_params_for_minEfrombiosimulators_simularium.execimportgenerate_simularium_file# define the working dirworking_dir='biosimulators_simularium/tests/fixtures/MinE'# define the simularium filepath (using the working dir as root in this case)simularium_fn=os.path.join(working_dir,'simplified-api-output')model_fp=os.path.join(working_dir,'model.txt')base_mass=12100density=1.0agent_params=generate_agent_params_for_minE(model_fp,base_mass,density)generate_simularium_file(working_dir=working_dir,simularium_filename=simularium_fn,agent_params=agent_params,model_fp=model_fp)try:assertos.path.exists(simularium_fn)print(f'{simularium_fn}has been successfully generated.')except:AssertionError('A simularium file could not be generated.')You may then navigate tohttps://simularium.allencell.org/viewerand drag/drop the newly generated simularium
file into the GUI window.We welcome any and all collaborations and/or raising of issues:To report an issue, please visitour Github issues page.To contact us, please send an email toapatrie@uchc.eduorinfo@biosimulators.org