iucm.model module

Classes

Output(cons, dist, entrop, rss, cons_det, …) The state of the model
Output2D(cons, dist, entrop, rss, cons_det, …) The 2D state variables of the model
PopulationModel(data, x, y[, …]) Class that runs and manages the population model

Data

fields Meta information for the variables in the 1D-output of the
fields2D Meta information for the variables in the 2D-output of the
class iucm.model.Output(cons, dist, entrop, rss, cons_det, cons_std, left_over, nscenarios)

Bases: tuple

The state of the model

The collections.namedtuple() defining the state of the model during a single step. Each field of this class corresponds to one output variable in the output netCDF of the PopulationModel. Meta information are taken from the fields dictionary

Parameters:
  • cons (float) – Energy consumption
  • dist (float) – Average distance between two individuals
  • entrop (float) – Entropy
  • rss (float) – Rank-Size Slope
  • cons_det (float) – The deterministic energy consumption based on iucm.energy_consumption.weights_LeNechet
  • cons_std (float) – The standard deviation of the energy consumption
  • left_over (float) – The left over inhabitants that could not be subtracted in the last step
  • nscenarios (float) – The number of scenarios that have been changed during this step

Attributes

cons Alias for field number 0
cons_det Alias for field number 4
cons_std Alias for field number 5
dist Alias for field number 1
entrop Alias for field number 2
left_over Alias for field number 6
nscenarios Alias for field number 7
rss Alias for field number 3

See also

Output2D, PopulationModel.state, PopulationModel.allocate_output

Create new instance of Output(cons, dist, entrop, rss, cons_det, cons_std, left_over, nscenarios)

cons

Alias for field number 0

cons_det

Alias for field number 4

cons_std

Alias for field number 5

dist

Alias for field number 1

entrop

Alias for field number 2

left_over

Alias for field number 6

nscenarios

Alias for field number 7

rss

Alias for field number 3

class iucm.model.Output2D(cons, dist, entrop, rss, cons_det, cons_std, left_over, nscenarios, scenarios)

Bases: tuple

The 2D state variables of the model

2D output variables. Each variable corresponds to the same variable as in 0-d Output objects, but instead of saving only the best state of the model, this output saves all scenarios

Parameters:
  • cons (np.ndarray of dtype float) – Energy consumption
  • dist (np.ndarray of dtype float) – Average distance between two individuals
  • entrop (np.ndarray of dtype float) – Entropy
  • rss (np.ndarray of dtype float) – Rank-Size Slope
  • cons_det (np.ndarray of dtype float) – The deterministic energy consumption based on iucm.energy_consumption.weights_LeNechet
  • cons_std (np.ndarray of dtype float) – The standard deviations within each probabilistic scenario
  • left_over (float) – The left over inhabitants that could not be subtracted in the last step
  • nscenarios (float) – The weight of each scenario that has been used during this step
  • scenarios (np.ndarray of dtype int) – The number of the scenario

Attributes

cons Alias for field number 0
cons_det Alias for field number 4
cons_std Alias for field number 5
dist Alias for field number 1
entrop Alias for field number 2
left_over Alias for field number 6
nscenarios Alias for field number 7
rss Alias for field number 3
scenarios Alias for field number 8

See also

Output, PopulationModel.state2d

Create new instance of Output2D(cons, dist, entrop, rss, cons_det, cons_std, left_over, nscenarios, scenarios)

cons

Alias for field number 0

cons_det

Alias for field number 4

cons_std

Alias for field number 5

dist

Alias for field number 1

entrop

Alias for field number 2

left_over

Alias for field number 6

nscenarios

Alias for field number 7

rss

Alias for field number 3

scenarios

Alias for field number 8

class iucm.model.PopulationModel(data, x, y, selection_method='consecutive', update_method='categorical', ncells=4, categories=None, state=None, forcing=None, probabilistic=0, max_pop=None, use_pctls=False, last_step=0, data2modify=None)[source]

Bases: object

Class that runs and manages the population model

This class represents one instance of the model for one experiment and is responsible for all the computation, parallelization and input-output coordination. The major important features of this class are

from_da() method
A classmethod to construct the model from a xarray.DataArray
step() method
The method that is brings the model to the next step
init_step_methods and update_methods
The available update methods how to bring the model to the next change
selection_methods
The available selection methods that define the available scenarios
update_methods
The available update methods that define how the population change for the given selection is pursued
state attribute
The current state of the model. It’s an instance of the Output class containing all 1D-variables of the current data attribute

Methods

allocate_output(da, dsi, steps) Create the dataset for the output
best_scenario(all_slices, all_indices) Compute the best scenario
categorical_update(cell_values, slicer) Change the values through an update to the next category
consecutive_selection()
distribute_probabilistic(slices, nscenarios) Redistribute the population increase to the best scenarios
from_da(da, dsi[, ofiles, osteps, …]) Construct the model from a psyplot.data.InteractiveArray
get_input_ds(data, dsi, \*\*kwargs) Return the input dataset which can be concatenated with the output
initialize_model(da, dsi, ofiles, osteps[, mask]) Initialize the model on the I/O processor
random_selection()
randomized_update(cell_values, slicer) Change the values through an update to a number within the next
start_processes(nprocs) Start nprocs processes for the model
step() Bring the model to the next step and eventually write the output
stop_processes() Stop the processes for the model
subtract_random() Subtract the people moving during this timestep
sync_state(sl, cell_values[, state, weights]) Synchronize the data attribute between the processes
value_update(cell_values, slicer[, remaining]) Change the cells by using the forcing
write() Write the current state to the output dataset
write_output([complete]) Write the data to the next netCDF file

Attributes

consumption Energy consumption
current_step The current step since the last output.
data np.ndarray. The current simulation data of the model
data2modify np.ndarray. The positions of the points in data that can be
dist Denumerator of average distance between two individuals
init_step The step initialization method from init_step_methods we use to
init_step_methods Mapping from update_method name to the corresponding init function
left_over Left over population that could not have been subtracted for within
movement The population movement during this time step
ncells int. The number of cells that are modified for one scenario
nprocs int. The number of processes started for this model
output_written Flag that is True if the data was written to a file during the last
population_change The population change during this time step
procs multiprocessing.Process. The processes of this model
select The selection method from selection_methods we use to define the
selection_methods Mapping from selection_method name to the corresponding function
state The state as a namedtuple.
state2d The different values from the state of the model for each
state2d_dict The state as a dictionary.
state_dict The state as a dictionary.
total_change The total population change during this time step
total_step The absolute current step in case the model has been restarted.
total_step_run The current step since the initialization of the model.
update The update method from update_methods we use to compute that
update_methods Mapping from update_method name to the corresponding function
x np.ndarray. The x-coordinates of the points in data
y np.ndarray. The y-coordinates of the points in data

Most of the other routines are related to input/output and parallelization

Parameters:
  • data (np.ndarray) – The 1D-data array (without NaN!) of the model
  • x (np.ndarray) – The x-coordinates in km of each point in data (same shape as data)
  • y (np.ndarray) – The y-coordinates in km of each point in data (same shape as data)
  • selection_method ({ 'consecutive' | 'random' }) – The avaiable selection scenarios (see selection_methods)
  • update_method ({ 'categorical' | 'random' | 'forced' }) – The avaiable update methods (see update_methods)
  • ncells (int) – The number of cells that shall be modified for one scenario. The higher the number, the less computationally expensive is the computation
  • categories (list of str) – The categories to use. If update_method is 'categorical', it describes the categories and if use_pctls is True, it the each category is interpreted as a quantile in data
  • state (list of float) – The current state of data. Must be a list corresponding to the Output class
  • forcing (xarray.Dataset) – The input dataset for the model containing variables with population evolution information. Possible variables in the netCDF file are movement containing the number of people to move and change containing the population change (positive or negative)
  • probabilistic (int or tuple) – The number of probabilistic scenarios. For each scenario the energy consumption is calculated and the final population is distributed to the cells with the ideal energy consumption. Set this to 0 to only use the weights by [LeNechet2012]. If tuple, then they are considered as the weights
  • max_pop (np.ndarray) – A 1d-array with the maximum population for each cell in data. If None, the last value in categories will be used
  • use_pctls (bool) – If True, values given in categories are interpreted as quantiles
  • last_step (int) – If the model is restarted, the total number of already made steps (see total_step attribute)
  • data2modify (np.ndarray) – The indices of points in data which are allowed to be modified. If None, all points are allowed to be modified

See also

from_da
A more convenient initialization method using a xarray.Dataset
allocate_output(da, dsi, steps)[source]

Create the dataset for the output

Parameters:
best_scenario(all_slices, all_indices)[source]

Compute the best scenario

This method computes the best scenario for the given scenarios defined through the given slices and indices

Parameters:
  • slices (list of None, slice or boolean arrays) – The slicing objects for each scenario that allow us to create a view of the data attribute that we modify in place. If list of None, it is computed using indices
  • indices (list of list of :class`int`) – The numpy array containing the integer position in data of the cells modified for each scenario
Returns:

  • 1-dim np.ndarray of dtype float – The consumptions of the best scenarios for each set of weights used
  • 2-dim np.ndarray of dtype float with shape (nprob, len(self.state)) – The state of the best scenario for each probabilistic scenario which can be used for the state attribute.
  • list of slice or boolean array – The slicing object from slices that corresponds to the best scenario and can be used to create a view on the data
  • list of list of float – The numbers of the modified cells for the best scenario
  • list of 2d-np.ndarrays – The 2d variables of the state2d attribute
categorical_update(cell_values, slicer)[source]

Change the values through an update to the next category

This method increases the population by updating the cells to the next (possible) category

consecutive_selection()[source]
consumption

Energy consumption

current_step = -1

The current step since the last output. -1 means, output has just been written or the model has been initialized

data = None

np.ndarray. The current simulation data of the model

data2modify = None

np.ndarray. The positions of the points in data that can be modified

dist

Denumerator of average distance between two individuals

distribute_probabilistic(slices, nscenarios)[source]

Redistribute the population increase to the best scenarios

This method distributes the population changes to the cells that have been computed as the best scenarios. It takes the input of the best_scenario() method

Parameters:slices (list) – The slicers of the best scenarios
classmethod from_da(da, dsi, ofiles=None, osteps=None, coord_transform=1, **kwargs)[source]

Construct the model from a psyplot.data.InteractiveArray

Parameters:
  • data (xr.DataArray) – The dataarray during the initialization
  • dsi (xr.Dataset) – The base dataset of the da
  • ofiles (list of str) – The name of the output files
  • osteps (list of int) – Steps when to make the output
  • coord_transform (float) – The transformation factor to transform the coordinate values into kilometres
Returns:

The model created ready to use
Return type:

PopulationModel
classmethod get_input_ds(data, dsi, **kwargs)[source]

Return the input dataset which can be concatenated with the output

Parameters:
  • data (xr.DataArray) – The dataarray during the initialization
  • dsi (xr.Dataset) – The base dataset of the da
Returns:

The modified dsi
Return type:

xr.Dataset
init_step = None

The step initialization method from init_step_methods we use to define the scenarios

init_step_methods

Mapping from update_method name to the corresponding init function

This property defines the init_step methods. Those methods are called at the beginning of each step on the main processor (I/O-processor). Each init_step method must accept no arguments and return a tuple with

  • an slice object or boolean array containing the information where the data changed
  • the indices of the cells in data that changed
initialize_model(da, dsi, ofiles, osteps, mask=None)[source]

Initialize the model on the I/O processor

Parameters:
  • data (xr.DataArray) – The dataarray during the initialization
  • dsi (xr.Dataset) – The base dataset of the da
  • ofiles (list of str) – The name of the output files
  • osteps (list of int) – Steps when to make the output
  • mask (np.ndarray) – A boolean array that maps from the data attribute into the 2D output data array
left_over

Left over population that could not have been subtracted for within the PopulationModel.value_update() method and should be considered in the next step

movement

The population movement during this time step

ncells = 4

int. The number of cells that are modified for one scenario

nprocs

int. The number of processes started for this model

output_written = False

Flag that is True if the data was written to a file during the last step

population_change

The population change during this time step

procs = None

multiprocessing.Process. The processes of this model

random_selection()[source]
randomized_update(cell_values, slicer)[source]

Change the values through an update to a number within the next category

This method increases the population by updating the cells to a random value within the next (possible) category

select = None

The selection method from selection_methods we use to define the scenarios

selection_methods

Mapping from selection_method name to the corresponding function

This property defines the selection methods. Those methods are called at the beginning of each step on the main processor (I/O-processor). Each selection_step method must accept no arguments and return a tuple with

  • an slice object or boolean array containing the information where the data changed. Alternatively it can be a list of None and those slicing objects will be computed from the second argument
  • a 2D list of dtype integer containing the indices of the cells that for changed for the corresponding scenario
start_processes(nprocs)[source]

Start nprocs processes for the model

state

The state as a namedtuple. You may set it with an iterable defined by the Output class

state2d

The different values from the state of the model for each of the scenarios

state2d_dict

The state as a dictionary. Mapping from state variable to the corresponding value. You may also set it with a dictionary

state_dict

The state as a dictionary. Mapping from state variable to the corresponding value. You may also set it with a dictionary

step()[source]

Bring the model to the next step and eventually write the output

This method is the core of the entire PopulationModel API connecting the necessary functions to compute the next best scenario. The general structure is

  1. initialize the step (see init_step_methods)
  2. define the scenarios (see selection_methods)
  3. choose the best scenario (see best_scenario and update_methods)
  4. write the output (see write() method)

Depending on whether the start_processes() method has been called earlier, this is either done serial or in parallel

stop_processes()[source]

Stop the processes for the model

subtract_random()[source]

Subtract the people moving during this timestep

sync_state(sl, cell_values, state=None, weights=None)[source]

Synchronize the data attribute between the processes

This method is called to synchronize the states of the model in the different processes

Parameters:
  • sl (slice or boolean np.ndarray) – The slicer that can be used to create a view on the data
  • cell_values (np.ndarray of dtype float) – The values of the cells described by sl
  • state (Output) – The state of the model
total_change

The total population change during this time step

total_step = -1

The absolute current step in case the model has been restarted. If -1, the model has not yet been started

total_step_run = -1

The current step since the initialization of the model. -1 means, the model has been initialized

update = None

The update method from update_methods we use to compute that changes for each scenario

update_methods

Mapping from update_method name to the corresponding function

This property defines the update methods. Each update method must accept and return a 1D numpy array of dtype float64 containing a view of the data attribute. The data must be modified in place!

value_update(cell_values, slicer, remaining=None)[source]

Change the cells by using the forcing

This update method changes the given cells based upon the movement information and the population_change information from the forcing dataset

write()[source]

Write the current state to the output dataset

write_output(complete=True)[source]

Write the data to the next netCDF file

Parameters:complete (bool) – If True, write the complete dataset, otherwise only until the current step
x = None

np.ndarray. The x-coordinates of the points in data

y = None

np.ndarray. The y-coordinates of the points in data

iucm.model.fields = {'cons': {'long_name': 'Energy consumption', 'units': 'MJ / inh'}, 'cons_det': {'comments': 'Energy consumption calculated based on based on Le Nechet, 2012', 'long_name': 'Deterministic energy consumption', 'units': 'MJ / inh'}, 'cons_std': {'long_name': 'std. deviation of Energy consumption', 'units': 'MJ / inh'}, 'dist': {'long_name': 'Average distance between two individuals', 'units': 'km'}, 'entrop': {'long_name': 'Entropy', 'units': '-'}, 'left_over': {'long_name': 'Left over population that could not be subtracted', 'units': 'inhabitants'}, 'nscenarios': {'long_name': 'The number of scenarios that have been changed during this step', 'units': '-'}, 'rss': {'long_name': 'Rank-Size Slope', 'units': '-'}}

Meta information for the variables in the 1D-output of the PopulationModel

iucm.model.fields2D = {'cons': {'long_name': 'Energy consumption', 'units': 'MJ / inh'}, 'cons_det': {'comments': 'Energy consumption calculated based on based on Le Nechet, 2012', 'long_name': 'Deterministic energy consumption', 'units': 'MJ / inh'}, 'cons_std': {'long_name': 'std. deviation of Energy consumption', 'units': 'MJ / inh'}, 'dist': {'long_name': 'Average distance between two individuals', 'units': 'km'}, 'entrop': {'long_name': 'Entropy', 'units': '-'}, 'left_over': {'long_name': 'Left over population that could not be subtracted', 'units': 'inhabitants'}, 'nscenarios': {'long_name': 'The number of scenarios that have been changed during this step', 'units': '-'}, 'rss': {'long_name': 'Rank-Size Slope', 'units': '-'}, 'scenarios': {'long_name': 'Scenario identifier'}}

Meta information for the variables in the 2D-output of the PopulationModel