atomica.project

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.

Classes

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.

Parameters:
  • 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 Project.data 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]
…or…
[(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]
…or…
[(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:ParameterSet
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 Project.save(). Migration is automatically performed as part of the loading operation.

Parameters:filepath – The file path/name to load
Returns:A new Project instance
load_databook(databook_path=None, make_default_parset=True, do_run=True)[source]

Load a data spreadsheet

Parameters:
  • 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:

None

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

Create a ProgramSet given a progbook

Parameters:
  • progbook_path – Path to a program spreadsheet or an AtomicaSpreadsheet instance
  • name – The name to assign to the new ProgramSet
Returns:

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

make_parset(name='default')[source]

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

Parameters:
  • which (str) – String identifying type - one of ['parameter','budget','coverage','combined']
  • kwargs – Arguments to pass to appropriate Scenario constructor
Return type:

Scenario

Returns:

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

Parameters:
  • 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:

list

Returns:

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_scenarios(store_results=True)[source]

Run all active scenarios

Parameters:store_results (bool) – If True, results will be appended to the project
Return type:list
Returns: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.

Parameters:
  • 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)
Returns:

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

Parameters:
  • filename (Optional[str]) – Name of the file to save
  • folder (Optional[str]) – Optionally specify a folder
Return type:

str

Returns:

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]
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.

Parameters:
  • 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
Returns:

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