pydes

`Simulator(init=0, trace=True)`

Simulator is the central object of Py-DES and is used to model all the process and events of the system.

Its main objective is to schedule process and events and then execute them in a time-ordered way.

Parameters:

Name	Type	Description	Default
`init`	`int \| float \| datetime`	The initial simulation time specified as a float or datetime object.	`0`
`trace`	`bool`	Indicates whether tracing is enabled or not.	`True`

Simulators can be instantiated either using numeric time (float or int) or datetime time.

To create a Simulator with numeric time units simply ommit the argument or pass a specific until argument.

sim = Simulator(until=10)

If you prefer to use datetime objects, you can pass to the until argument a datetime object.

from datetime import datetime
sim = Simulator(until=datetime.max)

Once you created the Simulator object you can start modeling your procesess using its differents methods.

Methods:

Name	Description
`sleep`	Sleep for the given duration.
`sleep_until`	Sleep until the given simulation time.
`wait_for`	Suspends the process until a condition becomes true.
`schedule`	Activates a process either immediately (if both `at` and `after` are None) or after a delay.
`run`	Starts simulation.
`record`	records an event by passing a component a value and optionally a description.
`records`	returns a list with all the recors that were saved during the simulation.

`record(name, value, description=None)`

Record a simulation event.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name associated with the event.	required
`value`	`Any`	Value associated with the event.	required
`description`	`str \| None`	Description of the event.	`None`

`records()`

Get recorded simulation events.

Returns:

Type	Description
`list[Record]`	list of `Record` objects

`schedule(func, at=None, after=None)`

Schedules a function either immediately (if both at and after are None) or after a delay.

Parameters:

Name	Type	Description	Default
`func`	`Callable[[], None]`	A function to be scheduled and runned during the simulation.	required
`at`	`int \| float \| datetime \| None`	Simulation time to activate the process, default is None.	`None`
`after`	`int \| float \| timedelta \| None`	Delay activation with specified time, default is None.	`None`

sim = Simulator(until=10)

class Process:
    def __init__(self, sim:Simulation):
        self.sim = sim
    def main(self):
        while True:
            print("this is my process running")
            self.sim.sleep(10)

process = Process(sim)
sim.schedule(proc.main)

`wait_for(cond, timeout=None)`

Wait for a condition to become true.

Suspends this process until the condition becomes true.

Parameters:

Name	Type	Description	Default
`cond`	`Callable[[], bool]`	Function to test.	required
`timeout`	`int \| float \| timedelta \| None`	Maximum simulation time to wait for condition to become true, default is None.	`None`

`sleep(duration=None)`

Sleep for the given duration.

Parameters:

Name	Type	Description	Default
`duration`	`int \| float \| timedelta \| None`	Duration to sleep for.	`None`

`sleep_until(until=None)`

Sleep until the given simulation time.

Parameters:

Name	Type	Description	Default
`until`	`int \| float \| datetime \| None`	Simulation time to sleep until.	`None`

`now()`

Return current simulation time.

Returns:

Type	Description
`float \| datetime`	current time expressed as float or datetime depending on the initial simulation time.

`run(until=inf)`

Start simulation.

Parameters:

Name	Type	Description	Default
`until`	`int \| float \| datetime`	maximum simulation time expressed as datetime or float.	`inf`

`Monitor(sim, trace)`

The Monitor is simply a convenient class to record different events or moments during the simulation. Simulation without data analytics is useless.

The Monitor is used internally by the Simulator and is not ment to be used outside this context.

To record an event you simply have to call the record method o the simulator and pass 2 required parameters and optionally a third one.

from pydes.process import Component, Simulator

class Process(Component):
    def __init__(self, sim: Simulator):
        self.sim = sim

    def main(self):
        for _ in range(10):
            self.sim.record(self,"start waiting")
            self.sim.sleep(2)
            self.sim.record(self,"end waiting","this is an aditional description")

When the simulation runs, you'll see all you recorded events printed out. Besides, these records can be retreived for further analysis using the records from the Simulator.

To turn off the printing of the records during simulation, you can pass 'trace=False' to the Simulator constructor.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`trace`	`bool`	Indicates whether tracing is enabled or not.	required

`record(name, value, description)`

Record a simulation event.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name associated with the event.	required
`value`	`Any`	Value associated with the event.	required
`description`	`str \| None`	Description of the event.	required

`values()`

Get recorded simulation events.

Returns:

Type	Description
`list[Record]`	list of `Record` objects.

`Record(time, name, value, description)` `dataclass`

Stores information about a simulation event.

Parameters:

Name	Type	Description	Default
`time`	`float \| datetime`	simulation time.	required
`name`	`str`	The name of the record.	required
`value`	`Any`	the event value to record	required
`description`	`str \| None`	optional description of the recorded event	required

`Component`

Base class for components in the simulation.

Components are just an utility base class that tracks how many instances of itself are created. Its id property will be unique during the simulation.

This property is usefull to identify different components in the simulation without having to set an explicit name for them, however is not a requirement for the Simulation to run.

from pydes.process import Component, Simulator

# define the component with a main method
class Process(Component):
    def __init__(self, sim: Simulator):
        self.sim = sim

    def main(self):
        for _ in range(10):
            print(self.sim.now(),"waiting")
            self.sim.sleep(2)
            print(self.sim.now(),"waiting")

# create the simulator object
sim = Simulator()

# create an instance of the Component
process = Process(sim)

# schedule the process in the simulator
sim.schedule(process.main)

# now you can run the simulation
sim.run()

`Container(sim, capacity=inf)`

Bases: Component

Containers have the capability to acumulate and provide continuous amounts of what contains. It is particularly useful to model non discrete accumulators like Tanks.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`capacity`	`int \| float`	The capacity of the container, default is 1.	`inf`

Methods:

Name	Description
`get`	decrease the level of the container by some amount.
`put`	increase the level of the container by some amount.

`get(amount=1)`

Get some amount from the container.

Parameters:

Name	Type	Description	Default
`amount`	`int \| float`	The amount to get from the container, default is 1.	`1`

`put(amount=1)`

Put some amount into the container.

Parameters:

Name	Type	Description	Default
`amount`	`int \| float`	The amount to put into the container, default is 1.	`1`

`level()`

Get the current level of the container.

`capacity()`

Get the capacity of the container.

`Queue(sim, capacity=inf)`

Bases: Component

Queues are used to acumulate objects in a buffer and retrieved them from it.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`capacity`	`float \| int`	The maximun lenght of the queue.	`inf`

Methods:

Name	Description
`put`	tries to insert a new member into the queue and waits if the queue is full.
`get`	tries to get one member from the queue and waits if the queue is empty.

Constructor for Queue class.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required

`get()`

Get an item from the queue.

Waits until there is an item available in the queue.

Returns:

Name	Type	Description
`Any`	`Any`	The item retrieved from the queue.

`put(member)`

Put an item into the queue or waits if the queue is full.

Parameters:

Name	Type	Description	Default
`member`	`Any`	The item to be put into the queue.	required

`size()`

Get the size of the queue. Its equivalent to the number of member inside.

Returns:

Name	Type	Description
`int`	`int`	The number of items in the queue.

`Resource(sim, capacity=1)`

Bases: Component

Resources can be requested and released by components and therefore are really useful in modeling real world scenarios quere components must be shared among different processess.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`capacity`	`int`	The capacity of the resource, default is 1.	`1`

Methods:

Name	Description
`request`	tries to get the ownership of this `Resource` and waits if the resource is not avialable.
`release`	gives back the ownership of the `Resource` so that other user can make use of it.

`request(by)`

Request the resource.

If the resource is idle, the component can acquire it. Otherwise, it waits until the resource becomes idle.

Parameters:

Name	Type	Description	Default
`by`	`Component`	The component requesting the resource.	required

`release(by)`

Release the resource.

Parameters:

Name	Type	Description	Default
`by`	`Component`	The component releasing the resource.	required

Raises:

Type	Description
`PydesError`	If the component has not previously requested the resource.

`usage()`

Get the current usage of the resource.

`capacity()`

Get the capacity of the resource.

`is_idle()`

Check if the resource is idle.

`State(sim, value)`

Bases: Component

Represents a state in the simulation. It is highly recommended to use Enums to control the possible values that a State object can take.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`value`	`Any`	The initial value of the state.	required

Methods:

Name	Description
`set`	changes the state to a new provided value
`wait`	waits until a certain value is set in the State.

`set(value)`

Set the state to a new value.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The new value of the state.	required

`wait(value)`

Wait for the state to become a specific value.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to wait for.	required

`Event(sim)`

Bases: Component

An event can be waited and set by components. They are very useful to model trigger conditions and model interaction between different actors across the system.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required

Methods:

Name	Description
`wait`	a component can call the `wait` method and suspend its excecution until this event is set.
`set`	a component can call the `set` method and trigger the event. This causes all the waiting components to continue its excecution.

`set()`

Set the event.

`wait()`

Wait for the event to be set.

`Store(sim, capacity=1)`

Bases: Component

Stores are useful to save and retrieve objects. Stores can be use to insert any type of object but it requires all the objects to be of the same type.

Parameters:

Name	Type	Description	Default
`sim`	`Simulator`	The simulator instance.	required
`capacity`	`int`	The capacity of the store, default is infinity.	`1`

`get()`

Get an item from the store.

`put(item)`

Put an item into the store.

Parameters:

Name	Type	Description	Default
`item`	`Any`	The item to put into the store.	required

`level()`

Get the current level of the store.

`capacity()`

Get the capacity of the store.

pydes

Simulator(init=0, trace=True)

record(name, value, description=None)

records()

schedule(func, at=None, after=None)

wait_for(cond, timeout=None)

sleep(duration=None)

sleep_until(until=None)

now()

run(until=inf)

Monitor(sim, trace)

record(name, value, description)

values()

Record(time, name, value, description) dataclass

Component

Container(sim, capacity=inf)

get(amount=1)

put(amount=1)

level()

capacity()

Queue(sim, capacity=inf)

get()

put(member)

size()

Resource(sim, capacity=1)

request(by)

release(by)

usage()

capacity()

is_idle()

State(sim, value)

set(value)

wait(value)

Event(sim)

set()

wait()

Store(sim, capacity=1)

get()

put(item)

level()

capacity()

`Simulator(init=0, trace=True)`

`record(name, value, description=None)`

`records()`

`schedule(func, at=None, after=None)`

`wait_for(cond, timeout=None)`

`sleep(duration=None)`

`sleep_until(until=None)`

`now()`

`run(until=inf)`

`Monitor(sim, trace)`

`record(name, value, description)`

`values()`

`Record(time, name, value, description)` `dataclass`

`Component`

`Container(sim, capacity=inf)`

`get(amount=1)`

`put(amount=1)`

`level()`

`capacity()`

`Queue(sim, capacity=inf)`

`get()`

`put(member)`

`size()`

`Resource(sim, capacity=1)`

`request(by)`

`release(by)`

`usage()`

`capacity()`

`is_idle()`

`State(sim, value)`

`set(value)`

`wait(value)`

`Event(sim)`

`set()`

`wait()`

`Store(sim, capacity=1)`

`get()`

`put(item)`

`level()`

`capacity()`