Implements the Project user interface for Atomica

The Project class serves as the primary user interface for Atomica. Almost all functionality can be accessed via this interface.

A project is based around 5 major lists:
  1. parsets – an odict of parameter sets

  2. progsets – an odict of program sets

  3. scens – an odict of scenario structures

  4. optims – an odict of optimization structures

  5. results – an odict of results associated with parsets, scens, and optims

In addition, a project contains:
  1. data – loaded from the spreadsheet

  2. settings – timestep, indices, etc.

  3. various kinds of metadata – project name, creation date, etc.


Project([name, framework, databook, do_run])

Main simulation container

ProjectSettings([sim_start, sim_end, sim_dt])

class atomica.project.Project(name='default', framework=None, databook=None, do_run=True, **kwargs)[source]

Main simulation container

A Project provides a centralized point of storage when working with Atomica. It contains

  • A framework

  • Data

  • Parameters

  • Programs

  • Scenarios and optimizations

  • Results

Importantly, it is generally assumed that saving and loading work is done by saving and loading projects.

  • name

  • framework – a Framework to use. This could be - A filename to an Excel file on disk - An sc.Spreadsheet instance - A ProjectFramework instance - None (this should generally not be used though!)

  • databook – The path to a databook file. The databook will be loaded into and the spreadsheet saved to Project.databook

  • do_run – If True, a simulation will be run upon project construction

  • kwargs – These are passed to the :class`ProjectSettings` constructor

calibrate(parset=None, adjustables=None, measurables=None, max_time=60, save_to_project=True, new_name=None, default_min_scale=0.0, default_max_scale=2.0, default_weight=1.0, default_metric='fractional')[source]

Method to perform automatic calibration.

The adjustables argument should be a list in the form of…

[par_name_1, par_name_2, charac_name_1]

[(par_name_1, pop_1, min_scale_1, max_scale_1)

(par_name_2, None, min_scale_2, max_scale_2), (charac_name_1, pop_2, min_scale_3, max_scale_3)]

The former instructs specified parameter values for all populations to be varied between default scaling limits. The latter varies specified parameters for specified populations, within specified scaling limits. ‘None’ in the population position represents independent scaling across all populations.

The measurables argument should be a list in the form of…

[charac_name_1, charac_name_2]

[(charac_name_1, pop_1, weight_1, “fractional”)

(charac_name_2, None, weight_2, “wape”)]

The former calculates a ‘fractional’ data comparison metric across specified characteristics for all pops. The latter calculates its metric for specified populations and for both specified weights and metric types. ‘None’ represents combining the metric across all populations.

To calibrate a project-attached parameter set in place, provide its key as the new name argument to this method. Current fitting metrics are: “fractional”, “meansquare”, “wape” Note that scaling limits are absolute, not relative.

Return type


create_databook(databook_path=None, num_pops=1, num_transfers=0, num_interpops=0, data_start=2000.0, data_end=2020.0, data_dt=1.0)[source]

Generate an empty data-input Excel spreadsheet corresponding to the framework of this project.

static load(filepath)[source]

Load binary project file

This method is an alternate constructor that is used to load a binary file saved using Migration is automatically performed as part of the loading operation.


filepath – The file path/name to load


A new Project instance

load_databook(databook_path=None, make_default_parset=True, do_run=True)[source]

Load a data spreadsheet

  • databook_path – a path string, which will load a file from disk, or an sc.Spreadsheet containing the contents of a databook

  • make_default_parset – If True, a Parset called “default” will be immediately created from the newly-added data

  • do_run – If True, a simulation will be run using the new parset

Return type


load_progbook(progbook_path=None, name='default')[source]

Create a ProgramSet given a progbook

  • progbook_path – Path to a program spreadsheet or an AtomicaSpreadsheet instance

  • name – The name to assign to the new ProgramSet


The newly created ProgramSet (also stored in self.progsets)


Transform project data into a set of parameters that can be used in model simulations.

make_progbook(progbook_path=None, progs=None, data_start=None, data_end=None)[source]

Make a blank program databook

make_scenario(which='combined', **kwargs)[source]

Make new scenario and store in Project

  • which (str) – String identifying type - one of ['parameter','budget','coverage','combined']

  • kwargs – Arguments to pass to appropriate Scenario constructor

Return type



New scenario instance

optim(key=None, verbose=2)[source]

Shortcut for getting an optimization

parset(key=None, verbose=2)[source]

Shortcut for getting a parset

plot(results=None, key=None, outputs=None, pops=None)[source]
progset(key=None, verbose=2)[source]

Shortcut for getting a progset

result(key=None, verbose=2)[source]

Shortcut for getting an result – a little special since they don’t have a fixed type

run_optimization(optimname=None, maxtime=None, maxiters=None, store_results=True)[source]

Run an optimization

run_sampled_sims(parset, progset=None, progset_instructions=None, result_names=None, n_samples=1, parallel=False, max_attempts=None)[source]

Run sampled simulations

This method samples from the parset (and progset if provided). It is separate from run_sim for several reasons

  • To avoid inadvertantly blowing up the size of the project, run_sampled_sims does not support automatic result saving

  • run_sim always returns a Result - if rolled into one functions, the return type would not be predictable

  • run_sim only takes in a single ProgramInstructions and result_name whereas run_sampled_sims supports iteration

    over multiple instructions

This method is different from proj.run_sim(samples=n_samples) in two ways -

The other common scenario is having multiple results

  • n_samples (int) – An integer number of samples

  • parset – A ParameterSet instance

  • progset – Optionally a ProgramSet instance

  • progset_instructions – This can be a list of instructions

  • result_names – Optionally specify names for each result. The most common usage would be when passing in a list of program instructions corresponding to different budget scenarios. The result names should be a list the same length as the instructions, or containing a single element if not using programs.

  • parallel – If True, run simulations in parallel (on Windows, must have if __name__ == '__main__' gating the calling code)

  • max_attempts – Number of retry attempts for bad initializations

Return type



A list of Results that can be passed to Ensemble.update(). If multiple instructions are provided, the return value of this function will be a list of lists, where the inner list iterates over different instructions for the same parset/progset samples. It is expected in that case that the Ensemble’s mapping function would take in a list of results


Run all active scenarios


store_results (bool) – If True, results will be appended to the project

Return type



List of results (one for each active scenario)

run_sim(parset=None, progset=None, progset_instructions=None, store_results=False, result_name=None)[source]

Run a single simulation

This function is the main entry point for running model simulations, given a parset and optionally program set + instructions.

  • parset – A ParameterSet instance, or the name of a parset contained in self.parsets. If None, then the most recently added parset will be used (the last entry in self.parsets)

  • progset – Optionally pass in a ProgramSet instance, or the name of a progset contained in self.progsets

  • progset_instructions – A ProgramInstructions instance. Programs will only be used if a instructions are provided

  • store_results – If True, then the result will automatically be stored in self.results

  • result_name (Optional[str]) – Optionally assign a specific name to the result (otherwise, a unique default name will automatically be selected)


A Result instance

save(filename=None, folder=None)[source]

Save binary project file

This method saves the entire project as a binary blob to disk

  • filename (Optional[str]) – Name of the file to save

  • folder (Optional[str]) – Optionally specify a folder

Return type



The full path of the file that was saved

scen(key=None, verbose=2)[source]

Shortcut for getting a scenario

update_settings(sim_start=None, sim_end=None, sim_dt=None)[source]

Modify the project settings, e.g. the simulation time vector.

class atomica.project.ProjectSettings(sim_start=None, sim_end=None, sim_dt=None)[source]
property tvec
update_time_vector(start=None, end=None, dt=None)[source]

Calculate time vector.

atomica.project._run_sampled_sim(proj, parset, progset, progset_instructions, result_names, max_attempts=None)[source]

Internal function to run simulation with sampling

This function is intended for internal use only. It’s purpose is to facilitate the implementation of parallelization. It should normally be called via Project.run_sim().

This standalone function samples and runs a simulation. It is a standalone function rather than a method of Project or Ensemble so that it can be pickled for use in sc.parallelize (otherwise, an error relating to not being able to pickle local functions or the base class gets raised).

A sampled simulation may result in bad initial conditions. If that occurs, the parameters and program set will be resampled up to a maximum of n_attempts times, after which an error will be raised.

  • proj – A Project instance

  • parset – A ParameterSet instance

  • progset – A ProgramSet instance

  • progset_instructions (list) – A list of instructions to run against a single sample

  • result_names (list) – A list of result names (strings)

  • max_attempts (Optional[int]) – Maximum number of sampling attempts before raising an error


A list of results that either contains 1 result, or the same number of results as instructions