atomica.project.Project

class atomica.project.Project(name='default', framework=None, databook=None, do_run=True, sim_start=None, sim_end=None, sim_dt=None)

Bases: NamedItem

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 (bool) – If True, a simulation will be run upon project construction

• sim_start (float) – Optionally specify the sim start year (otherwise will default to the first year in the databook)

• sim_end (float) – Optionally specify simulation end year

• sim_dt (float) – Optionally specify simulation timestep

NamedItem constructor

A name must be a string

Parameters:

name

Attributes

parsets

Dictionary of ParameterSet instances

Methods

calibrate	Method to perform automatic calibration.
copy
create_databook	Generate an empty data-input Excel spreadsheet corresponding to the framework of this project.
load	Load binary project file
load_databook	Load a data spreadsheet
load_progbook	Create a ProgramSet given a progbook
make_parset	Transform project data into a set of parameters that can be used in model simulations.
make_progbook	Save a blank program book
make_scenario	Make new scenario and store in Project
optim	Shortcut for getting an optimization
parset	Shortcut for getting a parset
plot
progset	Shortcut for getting a progset
result	Shortcut for getting an result -- a little special since they don't have a fixed type
run_optimization	Run an optimization
run_sampled_sims	Run sampled simulations
run_scenarios	Run all active scenarios
run_sim	Run a single simulation
save	Save binary project file
scen	Shortcut for getting a scenario
update_settings	Modify the project settings, e.g. the simulation time vector.

calibrate(parset=None, adjustables=None, measurables=None, max_time=60, save_to_project=False, new_name=None, default_min_scale=0.0, default_max_scale=2.0, default_weight=1.0, default_metric='fractional', **kwargs)

Method to perform automatic calibration.

Return type:

ParameterSet

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.

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

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

static load(filepath)

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, make_default_parset=True, do_run=True)

Load a data spreadsheet

Parameters:

• databook_path – Databook input. Supported inputs are: - A path string, which will load a file from disk - An sc.Spreadsheet containing the contents of a databook - A ProjectData instance

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

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

Return type:

None

load_progbook(progbook_path=None, name='default')

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')

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)

Save a blank program book

This method will create a temporary ProgramSet and save it to the requested path

Parameters:

• progbook_path (str) – Path to save program book

• progs – A program specification supposed by ProgramSet.new()

• data_start (float) – The start year for data entry

• data_end (float) – The end year for data entry

Return type:

str

Returns:

The full path of the newly created program book

make_scenario(which='combined', **kwargs)

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)

Shortcut for getting an optimization

parset(key=None, verbose=2)

Shortcut for getting a parset

parsets

Dictionary of ParameterSet instances

progset(key=None, verbose=2)

Shortcut for getting a progset

result(key=None, verbose=2)

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)

Run an optimization

run_sampled_sims(parset, progset=None, progset_instructions=None, result_names=None, n_samples=1, parallel=False, max_attempts=None, num_workers=None)

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 function, 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

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

• num_workers – If parallel is True, this determines the number of parallel workers to use (default is usually number of CPUs)

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)

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)

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 (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)

Save binary project file

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

Parameters:

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

• folder (str) – Optionally specify a folder

Return type:

str

Returns:

The full path of the file that was saved

scen(key=None, verbose=2)

Shortcut for getting a scenario

update_settings(sim_start=None, sim_end=None, sim_dt=None)

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