simulation module

class simulation.MIP(activities: List[ActivityData], utility_parameters: Dict, travel_times: Dict, distances: Optional[Dict] = None, period: int = 24, *args, **kwargs)[source]

Bases: OptimModel

This class instanciates a MIP optimisation model (relies on docplex library).

  • solver: String, ‘MIP’

  • activities: List of unique activities (ActivityData objects) to be scheduled

  • utility_parameters: Dictionary containing non activity-specific parameters to use in the utility function. The format should be {param: value}.

  • travel_times: Dictionary containing the mode specific travel times. The format should be {mode: {origin: {destination_1: travel time, destination_2…}}}

  • distances: Dictionary containing the mode specific distances. The format is the same as travel_times.

  • period: Time budget in hours. Default is 24h

  • model: model object

  • keys: unique labels of the activities to be scheduled

  • add_constraint: Adds a single constraint to the model object.

  • add_constraints: Adds multiple constraints to the model object, in batch.

  • initialize: Creates the model object, with decision variable and constraints (overrides parent method)

  • utility_function: Defines the activity-specific utility function (overrides parent method)

  • objective_function: Defines the schedule-specific utility function to be maximized (overrides parent method)

  • solve: Solves optimization problem

  • run: Runs the simulation

  • clear: Deletes model object and associated variables/constraints

  • check_input: checks if the input data is corret for the type of simulation selected (overrides parent method)

add_constraint(constraint) None[source]

Calls docplex add_constraint() function. Adds a single constraint to the model object.

Parameters:

Constraint (mathematical expression.) –

add_constraints(list_of_constraints: List) None[source]

Calls docplex add_constraints() function. Adds a list of constraints to the model object.

Parameters:

list_of_constraints (list of mathematical expressions.) –

clear() None[source]

Deletes model object and associated variables and constraints.

initialize() None[source]

Creates the model object, with decision variable and constraints

objective_function() float[source]

Objective function of the simulation, to be defined by the user. default is the sum of utility functions of all activities in schedule.

Returns:

of

Return type:

value of objective function for current decision variables

run(n_iter: int = 1, verbose: Union[bool, int] = False) Results[source]

Runs the simulation.

Parameters:
  • n_iter (-) –

  • verbose (-) –

Return type:

Object from Results class.

utility_function(activity: ActivityData) float[source]

Activity-specific utility function to be defined by the user. Default is linear utility with penalties for schedule deviations (start time and duration)

Parameters:

activity (ActivityData object) –

Returns:

utility

Return type:

value of activity specific utility for current decision variables

class simulation.MultidayMIP(activities: List[ActivityData], utility_parameters: Dict, travel_times: Dict, n_days: int, day_index: Optional[List] = None, distances: Optional[Dict] = None, period: int = 24, *args, **kwargs)[source]

Bases: OptimModel

This class instanciates a MIP optimisation model (relies on docplex library) for multiday analyses.

  • solver: String, ‘MultidayMIP’

  • activities: List of unique activities (ActivityData objects) to be scheduled

  • utility_parameters: Dictionary containing non activity-specific parameters to use in the utility function. The format should be {param: value}.

  • travel_times: Dictionary containing the mode specific travel times. The format should be {mode: {origin: {destination_1: travel time, destination_2…}}}

  • distances: Dictionary containing the mode specific distances. The format is the same as travel_times.

  • period: Time budget in hours. Default is 24h

  • n_days: Number of days. The total time horizon is computed a sn_days*period

  • day_index: List of indices of the days to be scheduled. (E.g., for a full week, [1,..,7] with 1 being Monday and 7 being Sunday)

  • model: model object

  • keys: unique labels of the activities to be scheduled

  • add_constraint: Adds a single constraint to the model object.

  • add_constraints: Adds multiple constraints to the model object, in batch.

  • initialize: Creates the model object, with decision variable and constraints (overrides parent method)

  • utility_function: Defines the activity-specific utility function (overrides parent method)

  • objective_function: Defines the schedule-specific utility function to be maximized (overrides parent method)

  • solve: Solves optimization problem

  • run: Runs the simulation

  • clear: Deletes model object and associated variables/constraints

add_constraint(constraint) None[source]

Calls docplex add_constraint() function. Adds a single constraint to the model object.

Parameters:

Constraint (mathematical expression.) –

add_constraints(list_of_constraints: List) None[source]

Calls docplex add_constraints() function. Adds a list of constraints to the model object.

Parameters:

list_of_constraints (list of mathematical expressions.) –

clear() None[source]

Deletes model object and associated variables and constraints.

initialize() None[source]

Creates the model object, with decision variable and constraints

objective_function() float[source]

Objective function of the simulation, to be defined by the user. default is the sum of utility functions of all activities in schedule.

Returns:

of

Return type:

value of objective function for current decision variables

run(n_iter: int = 1, verbose: Union[bool, int] = False) Results[source]

Runs the simulation.

Parameters:
  • n_iter (-) –

  • verbose (-) –

Return type:

Object from Results class.

utility_function(activity: ActivityData, day: int) float[source]

Activity-specific utility function to be defined by the user. Default is linear utility with penalties for schedule deviations (start time and duration)

Parameters:
  • activity (ActivityData object) –

  • day (index of day -- 1 is Monday and 7 is Sunday) –

Returns:

utility

Return type:

value of activity specific utility for current decision variables

class simulation.OptimModel(solver: str, activities: List[ActivityData], utility_parameters: Dict, optimality_target: int = 3, time_limit: int = 120, *args, **kwargs)[source]

Bases: object

This class instanciates an optimisation model.

  • solver: String, ‘MIP’ or ‘CP’

  • activities: List of unique activities (ActivityData objects) to be scheduled

  • utility_parameters: Dictionary containing non activity-specific parameters to use in the utility function. The format should be {param: value}.

  • opt_settings: Dictionary containing settings that will be passed to the solver

  • solve_status: Status of the optimisation problem

  • utility_function: defines the activity-specific utility function (overriden by children classes)

  • objective_function: defines the schedule-specific utility function to be maximized (overriden by children classes)

  • initialize: creates the model object, with decision variable and constraints (overriden by children classes)

  • check_input: checks if the input data is corret for the type of simulation selected (overriden by children classes)

check_input() None[source]

Checks if the input data is correct for the type of simulation

initialize() None[source]

Creates the model object, with decision variable and constraints (overriden by children classes)

objective_function() None[source]

Defines the schedule-specific utility function to be maximized (overriden by children classes)

utility_function() None[source]

Defines the activity-specific utility function (overriden by children classes)