OpenCLSim¶
This page lists all functions and classes available in the OpenCLSim.model and OpenCLSim.core modules. For examples on how to use these submodules please check out the Examples page, information on installing OpenCLSim can be found on the Installation page.
Submodules¶
The main components are the Model module and the Core module. All of their components are listed below.
openclsim.model module¶
-
class
openclsim.model.
Activity
(origin, destination, loader, mover, unloader, start_event=None, stop_event=None, show=False, *args, **kwargs)[source]¶ Bases:
openclsim.core.Identifiable
,openclsim.core.Log
The Activity Class forms a specific class for a single activity within a simulation. It deals with a single origin container, destination container and a single combination of equipment to move substances from the origin to the destination. It will initiate and suspend processes according to a number of specified conditions. To run an activity after it has been initialized call env.run() on the Simpy environment with which it was initialized.
To check when a transportation of substances can take place, the Activity class uses three different condition arguments: start_condition, stop_condition and condition. These condition arguments should all be given a condition object which has a satisfied method returning a boolean value. True if the condition is satisfied, False otherwise.
origin: object inheriting from HasContainer, HasResource, Locatable, Identifiable and Log destination: object inheriting from HasContainer, HasResource, Locatable, Identifiable and Log loader: object which will get units from ‘origin’ Container and put them into ‘mover’ Container
should inherit from Processor, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started loading and stopped loading- mover: moves to ‘origin’ if it is not already there, is loaded, then moves to ‘destination’ and is unloaded
- should inherit from Movable, HasContainer, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started moving, stopped moving, started loading / unloading and stopped loading / unloading
- unloader: gets amount from ‘mover’ Container and puts it into ‘destination’ Container
- should inherit from Processor, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started unloading and stopped unloading
- start_event: the activity will start as soon as this event is triggered
- by default will be to start immediately
- stop_event: the activity will stop (terminate) as soon as this event is triggered
- by default will be an event triggered when the destination container becomes full or the source container becomes empty
-
class
openclsim.model.
Simulation
(sites, equipment, activities, *args, **kwargs)[source]¶ Bases:
openclsim.core.Identifiable
,openclsim.core.Log
The Simulation Class can be used to set up a full simulation using configuration dictionaries (json).
sites: a list of dictionaries specifying which site objects should be constructed equipment: a list of dictionaries specifying which equipment objects should be constructed activities: list of dictionaries specifying which activities should be performed during the simulation
Each of the values the sites and equipment lists, are a dictionary specifying “id”, “name”, “type” and “properties”. Here “id” can be used to refer to this site / equipment in other parts of the configuration, “name” is used to initialize the objects name (required by core.Identifiable). The “type” must be a list of mixin class names which will be used to construct a dynamic class for the object. For example: [“HasStorage”, “HasResource”, “Locatable”]. The core.Identifiable and core.Log class will always be added automatically by the Simulation class. The “properties” must be a dictionary which is used to construct the arguments for initializing the object. For example, if “HasContainer” is included in the “type” list, the “properties” dictionary must include a “capacity” which has the value that will be passed to the constructor of HasContainer. In this case, the “properties” dictionary can also optionally specify the “level”.
Each of the values of the activities list, is a dictionary specifying an “id”, “type”, and other fields depending on the type. The supported types are “move”, “single_run”, “sequential”, “conditional”, and “delayed”. For a “move” type activity, the dictionary should also contain a “mover”, “destination” and can optionally contain a “moverProperties” dictionary containing an “engineOrder”. For a “single_run” type activity, the dictionary should also contain an “origin”, “destination”, “loader”, “mover”, “unloader” and can optionally contain a “moverProperties” dictionary containing an “engineOrder” and/or “load”. For a “sequential” type activity, the dictionary should also contain “activities”. This is a list off activities (dictionaries as before) which will be performed until sequentially in the order in which they appear in the list. For a “conditional” type activity, the dictionary should also contain a “condition” and “activities”, where the “activities” is another list of activities which will be performed until the event corresponding with the condition occurs. For a “delayed” type activity, the dictionary should also contain a “condition” and “activities”, where the “activities” is another list of activities which will be performed after the event corresponding with the condition occurs.
The “condition” of a “conditional” or “delayed” type activity is a dictionary containing an “operator” and one other field depending on the type. The operator can be “is_full”, “is_empty”, “is_done”, “any_of” and “all_of”. For the “is_full” operator, the dictionary should contain an “operand” which must be the id of the object (site or equipment) of which the container should be full for the event to occur. For the “is_empty” operator, the dictionary should contain an “operand” which must be the id of the object (site or equipment) of which the container should be empty for the event to occur. For the “is_done” operator, the dictionary should contain an “operand” which must the the id of an activity which should be finished for the event to occur. To instantiate such an event, the operand activity must already be instantiated. The Simulation class takes care of instantiating its activities in an order which ensures this is the case. However, if there is no such order because activities contain “is_done” conditions which circularly reference each other, a ValueError will be raised. For the “any_of” operator, the dictionary should contain “conditions”, a list of (sub)conditions of which any must occur for the event to occur. For the “all_of” operator, the dictionary should contain “conditions”, a list of (sub)conditions which all must occur for the event to occur.
-
openclsim.model.
conditional_process
(activity_log, env, stop_event, sub_processes)[source]¶ Returns a generator which can be added as a process to a simpy.Environment. In the process the given sub_processes will be executed until the given stop_event occurs. If the stop_event occurs during the execution of the sub_processes, the conditional process will first complete all sub_processes (which are executed sequentially in the order in which they are given), before finishing its own process.
activity_log: the core.Log object in which log_entries about the activities progress will be added. env: the simpy.Environment in which the process will be run stop_event: a simpy.Event object, when this event occurs, the conditional process will finish executing its current
run of its sub_processes and then finish- sub_processes: an Iterable of methods which will be called with the activity_log and env parameters and should
- return a generator which could be added as a process to a simpy.Environment the sub_processes will be executed sequentially, in the order in which they are given as long as the stop_event has not occurred.
-
openclsim.model.
delayed_process
(activity_log, env, start_event, sub_processes)[source]¶ “Returns a generator which can be added as a process to a simpy.Environment. In the process the given sub_processes will be executed after the given start_event occurs.
activity_log: the core.Log object in which log_entries about the activities progress will be added. env: the simpy.Environment in which the process will be run start_event: a simpy.Event object, when this event occurs the delayed process will start executing its sub_processes sub_processes: an Iterable of methods which will be called with the activity_log and env parameters and should
return a generator which could be added as a process to a simpy.Environment the sub_processes will be executed sequentially, in the order in which they are given after the start_event occurs
-
openclsim.model.
energy_use_sailing
(distance, current_speed, filling_degree, speed_max_full, speed_max_empty, propulsion_power_max, boardnet_power)[source]¶
-
openclsim.model.
get_loading_func
(property)[source]¶ Returns a loading_func based on the given input property. Input can be a flat rate or a table defining the rate depending on the level. In the second case, note that by definition the rate is the derivative of the level with respect to time. Therefore d level / dt = f(level), from which we can obtain that the time taken for loading can be calculated by integrating 1 / f(level) from current_level to desired_level.
-
openclsim.model.
get_unloading_func
(property)[source]¶ Returns an unloading_funct based on the given input property. Input can be a flat rate or a table defining the rate depending on the level. In the second case, note that by definition the rate is -1 times the derivative of the level with respect to time. Therefore d level / dt = - f(level), from which we can obtain the the time taken for unloading can be calculated by integrating 1 / f(level) from desired_level to current_level.
-
openclsim.model.
move_process
(activity_log, env, mover, destination, engine_order=1.0)[source]¶ Returns a generator which can be added as a process to a simpy.Environment. In the process, a move will be made by the mover, moving it to the destination.
activity_log: the core.Log object in which log_entries about the activities progress will be added. env: the simpy.Environment in which the process will be run mover: moves from its current position to the destination
should inherit from core.Movable- destination: the location the mover will move to
- should inherit from core.Locatable
- engine_order: optional parameter specifying at what percentage of the maximum speed the mover should sail.
- for example, engine_order=0.5 corresponds to sailing at 50% of max speed
-
openclsim.model.
sequential_process
(activity_log, env, sub_processes)[source]¶ Returns a generator which can be added as a process to a simpy.Environment. In the process the given sub_processes will be executed sequentially in the order in which they are given.
activity_log: the core.Log object in which log_entries about the activities progress will be added. env: the simpy.Environment in which the process will be run sub_processes: an Iterable of methods which will be called with the activity_log and env parameters and should
return a generator which could be added as a process to a simpy.Environment the sub_processes will be executed sequentially, in the order in which they are given
-
openclsim.model.
single_run_process
(activity_log, env, origin, destination, loader, mover, unloader, engine_order=1.0, filling=1.0, stop_reservation_waiting_event=None, verbose=False)[source]¶ Returns a generator which can be added as a process to a simpy.Environment. In the process, a single run will be made by the given mover, transporting content from the origin to the destination.
activity_log: the core.Log object in which log_entries about the activities progress will be added. env: the simpy.Environment in which the process will be run origin: object inheriting from HasContainer, HasResource, Locatable, Identifiable and Log destination: object inheriting from HasContainer, HasResource, Locatable, Identifiable and Log loader: object which will get units from ‘origin’ Container and put them into ‘mover’ Container
should inherit from Processor, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started loading and stopped loading- mover: moves to ‘origin’ if it is not already there, is loaded, then moves to ‘destination’ and is unloaded
- should inherit from Movable, HasContainer, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started moving, stopped moving, started loading / unloading and stopped loading / unloading
- unloader: gets amount from ‘mover’ Container and puts it into ‘destination’ Container
- should inherit from Processor, HasResource, Identifiable and Log after the simulation is complete, its log will contain entries for each time it started unloading and stopped unloading
- engine_order: optional parameter specifying at what percentage of the maximum speed the mover should sail.
- for example, engine_order=0.5 corresponds to sailing at 50% of max speed
- filling: optional parameter specifying at what percentage of the maximum capacity the mover should be loaded.
- for example, filling=0.5 corresponds to loading the mover up to 50% of its capacity
- stop_reservation_waiting_event: a simpy.Event, if there is no content available in the origin, or no space available
- in the destination, instead of performing a single run, the process will wait for new content or space to become available. If a stop_reservation_waiting_event is passed, this event will be combined through a simpy.AnyOf event with the event occurring when new content or space becomes available. This can be used to prevent waiting for new content or space indefinitely when we know it will not become available.
verbose: optional boolean indicating whether additional debug prints should be given.
openclsim.core module¶
Main module.
-
class
openclsim.core.
ContainerDependentMovable
(compute_v, *args, **kwargs)[source]¶ Bases:
openclsim.core.Movable
,openclsim.core.HasContainer
ContainerDependentMovable class
Used for objects that move with a speed dependent on the container level compute_v: a function, given the fraction the container is filled (in [0,1]), returns the current speed
-
current_speed
¶
-
-
class
openclsim.core.
ContainerDependentRouteable
(*args, **kwargs)[source]¶ Bases:
openclsim.core.ContainerDependentMovable
,openclsim.core.Routeable
ContainerDependentRouteable class
Used for objects that move with a speed dependent on the container level compute_v: a function, given the fraction the container is filled (in [0,1]), returns the current speed
-
current_speed
¶
-
-
class
openclsim.core.
DebugArgs
(*args, **kwargs)[source]¶ Bases:
object
Object that logs if leftover args are passed onto it.
-
class
openclsim.core.
DictEncoder
(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]¶ Bases:
json.encoder.JSONEncoder
serialize a simpy openclsim object to json
-
default
(o)[source]¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
-
-
class
openclsim.core.
EnergyUse
(energy_use_sailing=None, energy_use_loading=None, energy_use_unloading=None, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
EnergyUse class
energy_use_sailing: function that specifies the fuel use during sailing activity - input should be time energy_use_loading: function that specifies the fuel use during loading activity - input should be time energy_use_unloading: function that specifies the fuel use during unloading activity - input should be time
Example function could be as follows. The energy use of the loading event is equal to: duration * power_use.
- def energy_use_loading(power_use):
- return lambda x: x * power_use
-
class
openclsim.core.
EventsContainer
(*args, **kwargs)[source]¶ Bases:
simpy.resources.container.Container
-
empty_event
¶
-
full_event
¶
-
get
(amount)[source]¶ Request to get amount of matter from the container. The request will be triggered once there is enough matter available in the container.
Raise a
ValueError
ifamount <= 0
.
-
-
class
openclsim.core.
HasContainer
(capacity, level=0, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Container class
capacity: amount the container can hold level: amount the container holds initially container: a simpy object that can hold stuff
-
class
openclsim.core.
HasCosts
(dayrate=None, weekrate=None, mobilisation=None, demobilisation=None, *args, **kwargs)[source]¶ Bases:
object
Add cost properties to objects
-
cost
¶
-
-
class
openclsim.core.
HasDepthRestriction
(compute_draught, ukc, waves=None, filling=None, min_filling=None, max_filling=None, *args, **kwargs)[source]¶ Bases:
object
HasDepthRestriction class
Used to add depth limits to vessels draught: should be a lambda function with input variable container.volume waves: list with wave_heights ukc: list with ukc, corresponding to wave_heights
filling: filling degree [%] min_filling: minimal filling degree [%] max_filling: max filling degree [%]
-
current_draught
¶
-
-
class
openclsim.core.
HasPlume
(sigma_d=0.015, sigma_o=0.1, sigma_p=0.05, f_sett=0.5, f_trap=0.01, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Using values from Becker [2014], https://www.sciencedirect.com/science/article/pii/S0301479714005143.
The values are slightly modified, there is no differences in dragead / bucket drip / cutterhead within this class sigma_d = source term fraction due to dredging sigma_o = source term fraction due to overflow sigma_p = source term fraction due to placement f_sett = fraction of fines that settle within the hopper f_trap = fraction of fines that are trapped within the hopper
-
class
openclsim.core.
HasResource
(nr_resources=1, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
HasProcessingLimit class
Adds a limited Simpy resource which should be requested before the object is used for processing.
-
class
openclsim.core.
HasSoil
(*args, **kwargs)[source]¶ Bases:
object
Add soil properties to an object
soil = list of SoilLayer objects
-
class
openclsim.core.
HasSpill
(*args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Using relations from Becker [2014], https://www.sciencedirect.com/science/article/pii/S0301479714005143.
-
spillDredging
(processor, mover, density, fines, volume, dredging_duration, overflow_duration=0)[source]¶ Calculate the spill due to the dredging activity
density = the density of the dredged material fines = the percentage of fines in the dredged material volume = the dredged volume dredging_duration = duration of the dredging event overflow_duration = duration of the dredging event whilst overflowing
m_t = total mass of dredged fines per cycle m_d = total mass of spilled fines during one dredging event m_h = total mass of dredged fines that enter the hopper
m_o = total mass of fine material that leaves the hopper during overflow m_op = total mass of fines that are released during overflow that end in dredging plume m_r = total mass of fines that remain within the hopper
-
-
class
openclsim.core.
HasSpillCondition
(conditions, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Condition to stop dredging if certain spill limits are exceeded
limit = limit of kilograms spilled material start = start of the condition end = end of the condition
-
class
openclsim.core.
HasWeather
(dataframe, timestep=10, bed=None, waveheight_column='Hm0 [m]', waveperiod_column='Tp [s]', waterlevel_column='Tide [m]', *args, **kwargs)[source]¶ Bases:
object
HasWeather class
Used to add weather conditions to a project site name: name of .csv file in folder
year: name of the year column month: name of the month column day: name of the day column
timestep: size of timestep to interpolate between datapoints (minutes) bed: level of the seabed / riverbed with respect to CD (meters)
-
class
openclsim.core.
HasWorkabilityCriteria
(criteria, *args, **kwargs)[source]¶ Bases:
object
HasWorkabilityCriteria class
Used to add workability criteria
-
class
openclsim.core.
Identifiable
(name, ID=None, *args, **kwargs)[source]¶ Bases:
object
Something that has a name and id
name: a name id: a unique id generated with uuid
-
class
openclsim.core.
LoadingFunction
(loading_rate, load_manoeuvring=0, *args, **kwargs)[source]¶ Bases:
object
Create a loading function and add it a processor. This is a generic and easy to read function, you can create your own LoadingFunction class and add this as a mixin.
loading_rate: the rate at which units are loaded per second load_manoeuvring: the time it takes to manoeuvring in minutes
-
class
openclsim.core.
LoadingSubcycle
(loading_subcycle, *args, **kwargs)[source]¶ Bases:
object
loading_subcycle: pandas dataframe with at least the columns EventName (str) and Duration (int or float in minutes)
-
class
openclsim.core.
Locatable
(geometry, *args, **kwargs)[source]¶ Bases:
object
Something with a geometry (geojson format)
geometry: can be a point as well as a polygon
-
class
openclsim.core.
Log
(*args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Log class
log: log message [format: ‘start activity’ or ‘stop activity’] t: timestamp value: a value can be logged as well geometry: value from locatable (lat, lon)
-
class
openclsim.core.
Movable
(v=1, *args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
,openclsim.core.Locatable
Movable class
Used for object that can move with a fixed speed geometry: point used to track its current location v: speed
-
current_speed
¶
-
-
class
openclsim.core.
Processor
(*args, **kwargs)[source]¶ Bases:
openclsim.core.SimpyObject
Processor class
Adds the loading and unloading components and checks for possible downtime.
If the processor class is used to allow “loading” or “unloading” the mixins “LoadingFunction” and “UnloadingFunction” should be added as well. If no functions are used a subcycle should be used, which is possible with the mixins “LoadingSubcycle” and “UnloadingSubcycle”.
-
addSpill
(origin, destination, amount, duration)[source]¶ duration: duration of the activity in seconds origin: origin of the moved volume (the computed amount) destination: destination of the moved volume (the computed amount)
- There are three options:
- Processor is also origin, destination could have spill requirements
- Processor is also destination, origin could have spill requirements
- Processor is neither destination, nor origin, but both could have spill requirements
Result of this function is possible waiting, spill is added later on and does not depend on possible requirements
-
checkSpill
(mover, site, amount)[source]¶ duration: duration of the activity in seconds origin: origin of the moved volume (the computed amount) destination: destination of the moved volume (the computed amount)
- There are three options:
- Processor is also origin, destination could have spill requirements
- Processor is also destination, origin could have spill requirements
- Processor is neither destination, nor origin, but both could have spill requirements
Result of this function is possible waiting, spill is added later on and does not depend on possible requirements
-
check_possible_shift
(origin, destination, amount, activity)[source]¶ Check if all the material is available
If the amount is not available in the origin or in the destination yield a put or get. Time will move forward until the amount can be retrieved from the origin or placed into the destination.
-
computeEnergy
(duration, origin, destination)[source]¶ duration: duration of the activity in seconds origin: origin of the moved volume (the computed amount) destination: destination of the moved volume (the computed amount)
- There are three options:
- Processor is also origin, destination could consume energy
- Processor is also destination, origin could consume energy
- Processor is neither destination, nor origin, but both could consume energy
-
-
class
openclsim.core.
ReservationContainer
(*args, **kwargs)[source]¶ Bases:
simpy.resources.container.Container
-
reserve_get_available
¶
-
reserve_put_available
¶
-
-
class
openclsim.core.
Routeable
(*args, **kwargs)[source]¶ Bases:
openclsim.core.Movable
Moving folling a certain path
-
class
openclsim.core.
SimpyObject
(env, *args, **kwargs)[source]¶ Bases:
object
General object which can be extended by any class requiring a simpy environment
env: a simpy Environment
-
class
openclsim.core.
SoilLayer
(layer, volume, material, density, fines, *args, **kwargs)[source]¶ Bases:
object
Create a soillayer
layer = layer number, 0 to n, with 0 the layer at the surface material = name of the dredged material density = density of the dredged material fines = fraction of total that is fine material
-
class
openclsim.core.
SpillCondition
(spill_limit, start, end, *args, **kwargs)[source]¶ Bases:
object
Condition to stop dredging if certain spill limits are exceeded
limit = limit of kilograms spilled material start = start of the condition end = end of the condition
-
class
openclsim.core.
UnloadingFunction
(unloading_rate, unload_manoeuvring=0, *args, **kwargs)[source]¶ Bases:
object
Create an unloading function and add it a processor. This is a generic and easy to read function, you can create your own LoadingFunction class and add this as a mixin.
unloading_rate: the rate at which units are loaded per second unload_manoeuvring: the time it takes to manoeuvring in minutes
-
class
openclsim.core.
UnloadingSubcycle
(unloading_subcycle, *args, **kwargs)[source]¶ Bases:
object
unloading_subcycle: pandas dataframe with at least the columns EventName (str) and Duration (int or float in minutes)
-
class
openclsim.core.
WorkabilityCriterion
(event_name, condition, minimum=-inf, maximum=inf, window_length=datetime.timedelta(seconds=3600), *args, **kwargs)[source]¶ Bases:
object
WorkabilityCriterion class
Used to add limits to vessels (and therefore acitivities) event_name: name of the event for which this criterion applies condition: column name of the metocean data (Hs, Tp, etc.) minimum: minimum value maximum: maximum value window_length: minimal length of the window (minutes)
openclsim.server module¶
-
openclsim.server.
energy_use_plot_from_json
(jsonFile)[source]¶ Create a Gantt chart, based on a json input file
-
openclsim.server.
equipment_plot_from_json
(jsonFile)[source]¶ Create a Gantt chart, based on a json input file
-
openclsim.server.
save_simulation
(config, simulation, tmp_path='')[source]¶ Save the given simulation. The config is used to produce an md5 hash of its text representation. This hash is used as a prefix for the files which are written. This ensures that simulations with the same config are written to the same files (although it is not a completely foolproof method, for example changing an equipment or location name, does not alter the simulation result, but does alter the config file). The optional tmp_path parameter should only be used for unit tests.
Module contents¶
Top-level package for OpenCLSim.