Share experiments

We have integrated a feature into the carputils framework that allows to easily bundle a specific simulation in a structured data format. This bundle comprises all configuration information and data necessary to run and reproduce a simulation.

We also plan to offer to the possibility to share experiments easily by uploading them to a dedicated repository in the near future.

The bundle feature

The carputils framework now includes an option to create a self-contained bundle for a specific simulation including all necessary configuration information and data to reproduce the simulation.

Prerequisites

In order for a simulation to be correctly bundled, every file required to run it has to be included in the bundle.

In order for this condition to be satisfied, the following constraints have to be applied on the experiment script run.py:

  • every path to a required external file provided in the script has to be encapsulated in the carputils.tools.simfile_path() function.
  • In addition, if the file is a mesh file, the 'mesh' flag in the simfile_path() function has to be set to True.

The simfile_path() function allows carputils to find the files required for running your experiment. These files will then automatically be added to the bundle, and the path will be adapted so that your experiment can be run from within the bundle.

Here is a typical example of modifications that have to be done before creating a bundle from an experiment:

Original script

import os
from datetime import date
from carputils import tools

EXAMPLE_DIR = os.path.dirname(__file__)

[...]

@tools.carpexample(parser, jobID, clean_pattern='{}*|(.trc)'.format(date.today().year))
def run(args, job):

    #####################################
    #Perform the simulation
    #####################################
    cmd  = tools.carp_cmd(os.path.join(EXAMPLE_DIR, 'sim.par'))

    cmd += ['-stimulus[0].vtx_file', os.path.join(EXAMPLE_DIR, 'stim')]
    cmd += ['-meshname', os.path.join(EXAMPLE_DIR, 'mesh')]

[...]

Ready-to-bundle script

import os
from datetime import date
from carputils import tools

EXAMPLE_DIR = os.path.dirname(__file__)

[...]

@tools.carpexample(parser, jobID, clean_pattern='{}*|(.trc)'.format(date.today().year))
def run(args, job):

    #####################################
    #Perform the simulation
    #####################################
    cmd  = tools.carp_cmd(tools.simfile_path(os.path.join(EXAMPLE_DIR, 'sim.par')))

    cmd += ['-stimulus[0].vtx_file', tools.simfile_path(os.path.join(EXAMPLE_DIR, 'stim'))]
    cmd += ['-meshname', tools.simfile_path(os.path.join(EXAMPLE_DIR, 'mesh'), mesh=True)]

[...]

Creation of the bundle

Once the prequisites are satisfied, the bundle of the experiment can be created. In order to do so, launch the simulation you want to bundle (with all desired arguments) and add the --bundle option:

./run.py --your-arguments --bundle experiment_name

where experiment_name is the name that will be given to the bundle.

After the execution, an archive named experiment_name_bundle.zip will be created in your working directory. You can test the bundle by unzipping it and launching the experiment it contains, using the same command line as for the bundle creation (without the --bundle argument). The command line call is also stored in the METADATA.yml file of the bundle in the field named experiment_command_line.

Including metadata

When a bundle is created, a metadata file is automatically generated and included. This file contains autogenerated metadata such as:

  • the information about the creator found in the carputils settings file (name, email, ORCID)
  • the name given to the bundle
  • the command line to use in order to reproduce the bundled experiment
  • the python version used to create the bundle

Before generating the bundle, the user should provide a metadata file manually, containing some more information about the experiment. This file should be located in the same directory as the run.py script and be named METADATA.yml. This template contained in carputils shows which fields should be included: carputils/resources/METADATA.yml.tpl.

Including supplementary material

One should be aware that the external files included in the bundle are only those that are actually being used when running the experiment with the specific set of command line options chosen by the user. For example, if some files are only used when the --visualize option is used, then a bundle created without using this option could not contain these files.

For this reason (among others), it is possible to add additional files to a bundle manually:

  • if there is a folder named external in the same directory as run.py, its content will be added to the bundle automatically.
  • if there is a folder named Mesh in the same directory as run.py, its content will be added to the bundle automatically.
  • If the folder carputils.settings.config.MESH_DIR/experiment_name/ exists, then its content will be added to the bundle automatically.

Including simulation outputs

If a bundle is created for archiving a simulation, it can be useful to provide the output of the simulation in the bundle.

It is possible to do so by using the --bundle-output option in addition to the --bundle option.

This option creates a specific folder named sim_outputs in the bundle, in which the following folders are copied after the experiment ran (paths are given relatively to the experiment directory):

  • meshes (where meshes created on the fly are usually stored)
  • $jobID (where the outputs of the simulation are located)

Further steps

In the future, we plan to offer the possibility to upload these bundled experiments to a dedicated repository, so that they can be easily shared widely. It will also be possible to download the experiment configuration only and to get (potentially large) mesh data separately.

Subscribe to our newsletter and we will keep you posted.

For any questions, please use openCARP Q&A.

© Copyright 2020 openCARP project    Supported by DFG    Contact    Imprint and data protection