Simulation

class Simulation(model, register_stocks=False, n_temporal_units_to_sim=365, events_list=None, save_events=False, save_params=False, save_index=False, save_records=[], boario_output_dir='/tmp/boario3z33o8lx', results_dir_name=None, show_progress=False)

Bases: object

Defines a simulation object with a set of parameters and an IOSystem.

This class wraps a ARIOBaseModel or descendant, and create the context for simulations using this model. It stores execution parameters as well as events perturbing the model.

Methods

__init__(model[, register_stocks, ...])	A Simulation instance can be initialized with the following parameters:
add_event(ev)	Add an event to the simulation.
add_events(events)	Add a list of events to the simulation.
check_equilibrium(n_checks)	Checks the status of production, stocks and rebuilding demand.
event_compatibility(ev)	Checks if an event is compatible with current simulation environment
loop()	Launch the simulation loop.
next_step([check_period, min_steps_check, ...])	Advance the model to the next temporal step.
rebuild_events()	Updates rebuilding events from model's production dedicated to rebuilding.
recover_events()	Updates recovering events with their recovery function.
regions_compatible(regions)	Checks if given regions are all present in the simulation context.
reset_sim_full()	Resets the model to its initial status and remove all events.
reset_sim_with_same_events()	Resets the model to its initial status (without removing the events).
sectors_compatible(sectors)	Checks if given sectors are all present in the simulation context.
update_prod_cap_delta_arb()	Computes and sets the loss of production capacity from "arbitrary" sources.
update_prod_cap_delta_tot()	Computes and sets the loss of production capacity from both "arbitrary" sources and capital destroyed sources.
update_productive_capital_lost()	Computes current capital lost and updates production delta accordingly.
update_rebuild_demand()	Computes and updates total rebuilding demand based on a list of events.
write_index(index_file)	Writes the index of the dataframes used in the model in a json file.

Attributes

final_demand	Return the evolution of final demand asked of each industry as a DataFrame.
final_demand_unmet	Returns the evolution of the final demand that could not be answered by industries as a DataFrame.
inputs_stocks	Returns the evolution of the inventory amount of each input for each industry (region,sector) as a DataFrame.
intermediate_demand	Returns the evolution of intermediate demand asked of each industry (Total orders) as a DataFrame.
limiting_inputs	Returns the evolution of the inputs lacking for each industry (region,sector) as a DataFrame.
overproduction	Returns the evolution of the overproduction factor of each industry (region,sector) as a DataFrame.
production_capacity	Returns the evolution of the production capacity of each industry (region,sector) as a DataFrame.
production_realised	Returns the evolution of the production realised by each industry (region,sector) as a DataFrame.
productive_capital_to_recover	Retursn the evolution of remaining capital destroyed/to recover for each industry (region,sector) if it exists as a DataFrame.
rebuild_demand	Returns the evolution of rebuild demand asked of each industry (Total orders) as a DataFrame.
rebuild_prod	Returns the production allocated for the rebuilding demand by each industry (region,sector) as a DataFrame.
output_dir	pathlib.Path, optional: Optional path to the directory where output are stored.
results_storage	str: Name of the folder in output_dir where the results will be stored if saved.
model	Union[ARIOBaseModel, ARIOPsiModel] : The model to run the simulation with.
all_events	list[Event]: A list containing all events associated with the simulation.
n_temporal_units_to_sim	int: The total number of temporal_units to simulate.
current_temporal_unit	int: Tracks the number of temporal_units elapsed since simulation start.
records_storage	pathlib.Path: Place where records are stored if stored
params_dict	dict: A dictionary saving the parameters the simulation was run with.

output_dir

pathlib.Path, optional: Optional path to the directory where output are stored.

results_storage

str: Name of the folder in output_dir where the results will be stored if saved.

model

Union[ARIOBaseModel, ARIOPsiModel] : The model to run the simulation with. See ARIOBaseModel.

all_events

list[Event]: A list containing all events associated with the simulation.

n_temporal_units_to_sim

int: The total number of temporal_units to simulate.

current_temporal_unit

int: Tracks the number of temporal_units elapsed since simulation start. This may differs from the number of steps if the parameter n_temporal_units_by_step differs from 1 temporal_unit as current_temporal_unit is actually step * n_temporal_units_by_step.

records_storage

pathlib.Path: Place where records are stored if stored

params_dict

dict: A dictionary saving the parameters the simulation was run with.

loop()

Launch the simulation loop.

This method launch the simulation for the number of steps to simulate described by the attribute self.n_temporal_units_to_sim, calling the next_step() method. For convenience, it dumps the parameters used in the logs just before running the loop. Once the loop is completed, it flushes the different memmaps generated.

next_step(check_period=182, min_steps_check=None, min_failing_regions=None)

Advance the model to the next temporal step.

This method wraps all computation required to advance to the next step of the simulation.

First it checks if an event is planned to occur at the current step and if so, shocks the model with the corresponding event. Then:

0. If at least one step elapsed, it computes the new overproduction vector for the next step (using calc_overproduction())

1. Computes production for the current step. (See calc_production())

2. Distribute the realised production towards the different demands (intermediate, final, rebuilding) and compute the changes in the inputs stock matrix (see distribute_production())

Note that it is during this step that the model checks if an event is completely rebuild/recovered and removes it from the list the case being.

3. Computes the orders matrix (i.e. the intermediate demand) for the next step (see calc_orders())

Additionally, once every check_period steps elapsed, it checks for crash or equilibrium of the economy (see check_equilibrium()).

Parameters:

check_periodint

The time period in number of temporal units to wait between each “crash/equilibrium” check.

min_steps_checkOptional[int]

The minimum wait before the first check.

min_failing_regionsOptional[int]

The minimum number of failing regions required to consider economy has crashed.

check_equilibrium(n_checks)

Checks the status of production, stocks and rebuilding demand.

This methods checks and store the status of production, inputs stocks and rebuilding demand and store the information in self.equi.

At the moment, the following status are implemented:

• production and stocks can be greater (ie all industries are producing more), equi (ie all industries produce almost the same as at initial equilibrium (0.01 atol)), not equi (ie neither of the previous case)

• rebuilding demand can be finished or not finished depending if some events still have some rebuilding demand unanswered or if all are completely rebuilt.

Parameters:

n_checksint

The number of checks counter.

add_events(events)

Add a list of events to the simulation.

Parameters:

eventslist[Event]

The events to add.

add_event(ev)

Add an event to the simulation.

Parameters:

evEvent

The event to add.

event_compatibility(ev)

Checks if an event is compatible with current simulation environment

Parameters:

evEvent

The event to checks.

Raises:

ValueError

If one attribute of the event is not consistent with the simulation context.

regions_compatible(regions)

Checks if given regions are all present in the simulation context.

Parameters:

regionsRegionsList

The regions to checks.

Returns:

set

The set of regions not present in the model’s regions.

sectors_compatible(sectors)

Checks if given sectors are all present in the simulation context.

Parameters:

sectorsSectorsList

The sectors to checks.

Returns:

set

The set of sectors not present in the model’s regions.

rebuild_events()

Updates rebuilding events from model’s production dedicated to rebuilding.

This method loops through the event trackers and update the events depending on their allocated rebuilding production. If the received production is sufficient, then the events are flagged as “finished”, and removed from the tracker.

Raises:

RuntimeError

Raised if an event tracker has no rebuid_id (should not happen).

recover_events()

Updates recovering events with their recovery function.

This method loops through the event trackers and update the events depending on their recovery function.

Raises:

RuntimeError

Raised if an event tracker has no recovery function (should not happen).

update_rebuild_demand()

Computes and updates total rebuilding demand based on a list of events.

Computes and updates the model rebuilding demand from the event tracker. Only events tagged as rebuildable are accounted for. Both house_rebuild_demand and indus_rebuild_demand are updated.

update_productive_capital_lost()

Computes current capital lost and updates production delta accordingly.

Computes and sets the current stock of capital lost by each industry of the model due to the events. Also update the production capacity lost accordingly, by computing the ratio of capital lost to capital stock.

update_prod_cap_delta_arb()

Computes and sets the loss of production capacity from “arbitrary” sources.

Warning

If multiple events impact the same industry, only the maximum loss is accounted for.

update_prod_cap_delta_tot()

Computes and sets the loss of production capacity from both “arbitrary” sources and capital destroyed sources.

property production_realised

Returns the evolution of the production realised by each industry (region,sector) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the production realised, the columns are the industries

and the index is the step considered.

property production_capacity

Returns the evolution of the production capacity of each industry (region,sector) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the production capacity, the columns are the industries

and the index is the step considered.

property final_demand

Return the evolution of final demand asked of each industry as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the final demand asked, the columns are the industries

and the index is the step considered.

property intermediate_demand

Returns the evolution of intermediate demand asked of each industry (Total orders) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the intermediate demand asked, the columns are the industries

and the index is the step considered.

property rebuild_demand

Returns the evolution of rebuild demand asked of each industry (Total orders) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the rebuild demand asked, the columns are the industries

and the index is the step considered.

property overproduction

Returns the evolution of the overproduction factor of each industry (region,sector) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the overproduction factor, the columns are the industries

and the index is the step considered.

property final_demand_unmet

Returns the evolution of the final demand that could not be answered by industries as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the final demand not met, the columns are the industries

and the index is the step considered.

property rebuild_prod

Returns the production allocated for the rebuilding demand by each industry (region,sector) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the production allocated, the columns are the industries

and the index is the step considered.

property inputs_stocks

Returns the evolution of the inventory amount of each input for each industry (region,sector) as a DataFrame. Not this is not available if “record_stocks” is not set to True, as the DataFrame can be quite large for “classic” MRIOTs.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the amount in inventory, the columns are the industries

and the index are the step and input considered (MultiIndex).

property limiting_inputs

Returns the evolution of the inputs lacking for each industry (region,sector) as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is a boolean set to 1 if considered input constrains production, the columns are the industries

and the index are the step and input considered (MultiIndex).

property productive_capital_to_recover

Retursn the evolution of remaining capital destroyed/to recover for each industry (region,sector) if it exists as a DataFrame.

Returns:

pd.DataFrame: A pandas DataFrame where the value is the amount of capital (still) destroyed, the columns are the industries

and the index is the step considered.

reset_sim_with_same_events()

Resets the model to its initial status (without removing the events). [WIP]

reset_sim_full()

Resets the model to its initial status and remove all events.

write_index(index_file)

Writes the index of the dataframes used in the model in a json file.

See write_index() for a more detailed documentation.

Parameters:

index_fileUnion[str, pathlib.Path]

name of the file to save the indexes to.