ecoli.composites.ecoli_master

Composer used to generate the processes, steps, topology, and initial state of the E. coli whole cell model.

Note

Use the EcoliSim interface to configure and run simulations with this composer.

class ecoli.composites.ecoli_master.Ecoli(config)[source]

Bases: Composer

The main composer used to create the Composite that is given to Engine to run the E. coli whole cell model.

Loads pickled simulation data object (from ParCa, see fit_sim_data_1) and instantiates all processes and steps (also dynamically generates flow for steps).

load_sim_data

Instance of LoadSimData

config

Cached copy of config

processes_and_steps

Processes, steps, and flow generated by generate_processes_and_steps()

Parameters:

config (dict[str, Any]) – Configuration dictionary that is typically supplied by EcoliSim

defaults
{   'agent_id': '0',
    'agents_path': ('..', '..', 'agents'),
    'amp_lysis': False,
    'chromosome_path': ('unique', ' full_chromosome'),
    'daughter_path': (),
    'divide': False,
    'division_threshold': 668,
    'division_variable': ('listeners', 'mass', 'dry_mass'),
    'flow': {},
    'log_updates': False,
    'mar_regulon': False,
    'process_configs': {},
    'seed': 0,
    'sim_data_path': '/home/runner/work/vivarium-ecoli/vivarium-ecoli/reconstruction/sim_data/kb/simData.cPickle',
    'time_step': 2.0}

A subset of configuration options with default values for testing purposes (see ecoli_topology_plot()). For normal users, this composer should only be called indirectly via the EcoliSim interface, whose defaults are laid out in the JSON file at ecoli/composites/ecoli_configs/default.json.

generate_flow(config)[source]

Retrieve cached flow generated by generate_processes_and_steps() when generate() is called on this composer.

Parameters:

config (dict[str, Any]) –

Return type:

dict[str, list[tuple[str]]]

generate_processes(config)[source]

Retrieve cached processes generated by generate_processes_and_steps() when generate() is called on this composer.

Parameters:

config (dict[str, Any]) –

Return type:

dict[str, Process]

generate_processes_and_steps(config)[source]

Helper function that dynamically initializes all processes and steps (including their flow) according to options supplied in config. This method is called when Ecoli is initialized and its return value is cached as the instance variable processes_and_steps. This allows the initial_state method to be run before calling generate() on this composer.

Parameters:

config (dict[str, Any]) –

Important key-value pairs in this dictionary include:

  • process_configs:

    Mapping of process names (str) to process configs. The configs can either be dictionaries that will be used to initialize said process, the string "sim_data" to indicate that the process config should be loaded from the pickled simulation data object using get_config_by_name(), or the string "default" to indicate that the defaults attribute of the process should be used as its config.

  • processes:

    Mapping of all process names (str) to the Process, Step, or PartitionedProcess instances that they refer to.

  • log_updates:

    Boolean option indicating whether to emit the updates of all processes in config['processes'] (separately log the updates from the Requester and Evolver created from each PartitionedProcess) at the path ('log_update',) by wrapping them with make_logging_process(). See blame for a plotting script that can be used to visualize how each process changes bulk molecule counts.

  • flow:

    Mapping of process names to their dependencies. Note that the only names allowed must correspond to instances of either Step or PartitionedProcess. This method parses the names of partitioned processes and edits the flow to create the four execution layers detailed in Implementation.

  • divide:

    Boolean option that adds Division if true.

  • division_threshold:

    Config option for Division

  • agent_id:

    Config option for Division

  • d_period:

    Boolean option that only matters if division is true. Adds MarkDPeriod if true.

Returns:

Tuple consisting of a mapping of process names to fully initialized Process instances, a mapping of step names to fully initialized Step instances, and a flow describing the dependencies between steps.

Return type:

tuple[dict[str, Process], dict[str, Step], dict[str, tuple[str]]]

generate_steps(config)[source]

Retrieve cached steps generated by generate_processes_and_steps() when generate() is called on this composer.

Parameters:

config (dict[str, Any]) –

Return type:

dict[str, Step]

generate_topology(config)[source]

Creates simulation topology when generate() is called on this composer.

Parameters:

config (dict[str, Any]) –

Uses the same config supplied to this composer in Ecoli that was used to generate the processes and steps in generate_processes_and_steps(). Important key-value pairs include:

  • topology:

    Mapping of process names to topologies. Names of PartitionedProcess instances are automatically split into two separate topologies, one for the Requester and another for the Evolver that is created for each partitioned process (see Partitioning).

  • log_updates:

    Boolean, adds additional log_update topology path to write the updates of each process when true. See make_logging_process().

  • divide:

    Boolean, adds toplogy for Division when true.

  • d_period:

    Boolean, adds topology for MarkDPeriod when true.

Returns:

Full topology for an E. coli simulation.

Return type:

dict[str, tuple[str]]

initial_state(config=None)[source]

Users have three options for configuring the simulation initial state:

  1. config['initial_state']

2. Load the JSON file at f'data/{config['initial_state_file]}.json' using get_state_from_file().

3. Generate initial state from simulation data object (see generate_initial_state())

This method will go through these options in order until a dictionary is loaded. This dictionary will serve as the base initial state.

Users can override values in the initial state by specifying one or more override filenames in config['initial_state_overrides']. For each filename, the JSON at the path f'data/{override_filename}.json' is loaded. Bulk molecule overrides (anything under the bulk key in the loaded JSON) take the form of key-value pairs where keys are bulk molecule IDs and values are the desired counts of those molecules. These key-value pairs are parsed to change the desired counts for the correct rows in the bulk molecule structured Numpy array (see Bulk Molecules). All other overrides are directly used to update the initial state with no further processing.

As explained in Partitioning, instances of PartitionedProcess are turned into two Step instances in the final model: a Requester and an Evolver. To ensure that both of these steps have access to the same mutable parameters (e.g. if a Requester changes a parameter, the Evolver will see the change), this method places the the PartitionedProcess that they share into the simulation state under the ('process',) path.

Warning

This method will NOT work if run after calling generate() on this composer.

Parameters:

config (dict[str, Any]) – Defaults to the config used to initialize Ecoli

Returns:

Complete initial state for an E. coli simulation.

Return type:

dict[str, Any]

ecoli.composites.ecoli_master.ecoli_topology_plot(config=None)[source]
ecoli.composites.ecoli_master.run_ecoli(filename='default', total_time=10, divide=False, progress_bar=True, log_updates=False, emitter='timeseries', time_series=True)[source]

Run E. coli simulations.

Parameters:

  • total_time (int) – the total runtime of the experiment

  • divide (bool) – whether to incorporate division

  • progress_bar (bool) – whether to show a progress bar

  • log_updates (bool) – whether to save updates from each process (refer to make_logging_process())

  • emitter (str) – type of emitter to use (refer to emitter argument for Engine)

  • time_series (bool) – whether to return data in timeseries format (refer to query())

  • filename (str) –

Returns:

Data emitted by simulation.

Note

If data is not set up to be emitted to a MongoDB database (e.g. emitter is not database), users will not have easy access to the listener metadata that is emitted when emit_config is true (see EcoliSim, Engine, and listener_schema() for details).