SimCounter
- class pydsol.core.statistics.SimCounter(key: str, name: str, simulator: SimulatorInterface, *, producer: EventProducer | None = None, event_type: EventType | None = None)[source]
Bases:
EventBasedCounter
,SimStatisticsInterface
The SimCounter receive the observations in the same way as the EventBasedCounter statistics class, but this class is also aware of the Simulator. This means they can (a) subscribe to the Simulator’s WARMUP_EVENT taking care that the statistics are initialized appropriately, and (b) register themselves as output statistics in the model. The SimCounter can immediately register itself with an EventProducer for a certain EventType in the model, that will generate the data for the statistics object. The EventProducer and EventTypes to listen to can also be added later with the listen_to method.
Sending the events with observations is done by the EventProducer’s fire(…) method. This way, the statistic gathering and processing is decoupled from the process in the simulation that generates the data: there can be zero, one, or many statistics listeners for each data producing object in the simulation.
This event-based statistic object also fires timestamped events with the values of the calculated statistics values, so a GUI-element such as a graph or table can subscribe to this event-based statistics object and be automatically updated when values of the statistic change. Again, this provides decoupling and flexibility where on beforehand it is not known whether zero, one, or many (graphics or simulation) objects are interested in the values that this statistics object calculates.
The SimCounter is a simple statistics object that can count events or occurrences. Note that the number of observations is not necessarily equal to the value of the counter, since the counter allows any integer as the increment (or decrement) during an observation.
Given the fact that the SimCounter is linked to the Simulator, it is subscribed to the WARMUP_EVENT of the Simulator to initialize the statistics.
Note
Since the statistics need to be registered in the Model to ensure that they are captured and saved for the Experiment results, the instantiation of the SimCounter needs to be done in the construct_model method of the DSOLModel, and not in the constructor of the DSOLModel.
Example
In simulation, the SimCounter can be used to count arrivals, the number of processed entities in servers, the number of entities in the system, etc.
- Attributes:
_key (str) – the key by which the statistics object can be easily found
_name (str) – a descriptive name by which the statistics object can be identified
_n (int) – the number of observations
_count (int) – the current value of the counter
_simulator (SimulatorInterface) – the simulator
_event_types (set[EventType]) – the event types from EventProducers to listen to
- __init__(key: str, name: str, simulator: SimulatorInterface, *, producer: EventProducer | None = None, event_type: EventType | None = None)[source]
Construct a new SimCounter statistics object. The SimCounter can receive its observations by subscribing (listening) to one or more EventProducers that provides the values for the statistic using the EventProducer’s fire(…) method. This way, the statistic gathering and processing is decoupled from the process in the simulation that generates the data: there can be zero, one, or many statistics listeners for each data producing object in the simulation.
This event-based statistic object also fire events with the values of the calculated statistics values, so a GUI-element such as a graph or table can subscribe to this event-based statistics object and be automatically updated when values of the statistic change. Again, this provides decoupling and flexibility where on beforehand it is not known whether zero, one, or many (graphics or simulation) objects are interested in the values that this statistics object calculates.
The SimCounter is a simple statistics object that can count events or occurrences. Note that the number of observations is not necessarily equal to the value of the counter, since the counter allows any integer as the increment (or decrement) during an observation.
Given the fact that the SimCounter is linked to the Simulator, it is subscribed to the WARMUP_EVENT of the Simulator to initialize the statistics.
- Parameters:
key (str) – The key by which the statistics object can be easily found.
name (str) – A descriptive name by which the statistics object can be identified.
simulator (SimulatorInterface) – The simulator for subscribing to the WARMUP_EVENT and accessing the Model to register this output statistic.
producer (EventProducer (optional)) – A class (often a simulation object such as a Server-type object, a Queue, or an Entity) that extends EventProducer, and is able to fire DATA_EVENT to its listeners. This statistics object registers itself with the event producer for the specified event_type.
event_type (EventType (optional)) – The EventType that indicates the type of event we are interested in. By default use the DATA_EVENT, but when the notify-method is changed to also receive other types of events, the listen_to method can of course also register for these event-types, possibly with a different payload, as well.
- Raises:
TypeError – when key is not a string
TypeError – when name is not a string
TypeError – when simulator is not of type SimulatorInterface
TypeError – if producer is not None, but it is not an EventProducer
TypeError – if event_type is not None, but it is not an EventType
- listen_to(producer: ~pydsol.core.pubsub.EventProducer, event_type: ~pydsol.core.pubsub.EventType = EventType[StatEvents.DATA_EVENT metadata={self._metadata}])[source]
The statistics objects can register themselves with an EventProducer for a certain EventType in the model, that will generate the data for the statistics object. it is possible to call listen_to multiple time. In that case, the events from all EventProducers where this statistics object is registered, will be processed.
Sending the events with observations is done by the EventProducer’s fire(…) method. This way, the statistic gathering and processing is decoupled from the process in the simulation that generates the data: there can be zero, one, or many statistics listeners for each data producing object in the simulation.
- Parameters:
producer (EventProducer) – A class (often a simulation object such as a Server-type object, a Queue, or an Entity) that extends EventProducer, and is able to fire DATA_EVENT to its listeners. This statistics object registers itself with the event producer for the specified event_type.
event_type (EventType) – The EventType that indicates the type of event we are interested in. By default it is the DATA_EVENT, but when the notify-method is changed to also receive other types of events, the listen_to method can of course also register for these event-types as well.
- Raises:
TypeError – if producer is not an EventProducer
TypeError – if event_type is not an EventType
- property key: str
Return the key by which the statistics object can be easily found.
- Returns:
The key by which the statistics object can be easily found.
- Return type:
str
- property simulator: SimulatorInterface
Return the simulator. The statistic listens to the Simulator for the WARMUP-event.
- Returns:
An instance to the simulator to which this statistic is linked.
- Return type:
- notify(event: Event)[source]
The notify method is the method that is called by EventProducer where this object was added as a listener to register an observation. The EventType for the observation should typically be the StatEvents.DATA_EVENT and the payload should be a single integer. This value will be registered by the counter.
A second event to which the SimCounter listens automatically is the WARMUP_EVENT as fired by the Simulator. When that event is received, the statistics are initialized.
Other events are silently skipped.
- Parameters:
event (Event) – (1) The event fired by the EventProducer to provide data to the statistic. The event’s content should be a single int with the value. (2) The WARMUP_EVENT as fired by the Simulator. This event has no payload.
- Raises:
TypeError – when event is not of the type Event
ValueError – when the DATA_EVENT’s payload is not an int
- add_listener(event_type: EventType, listener: EventListener)
Add an EventListener to this EventProducer for a given EventType. If the listener already is registered for this EventType, this will be ignored.
- Parameters:
event_type (EventType) – the EventType for which this listener subscribes
listener (EventListener) – the subscriber to register for the provided Eventtype
- Raises:
EventError – if any of the arguments is of the wrong type
- count()
Return the current value of the counter statistic.
- Returns:
The current value of the counter statistic.
- Return type:
int
- has_listeners() bool
indicate whether this producer has any listeners or not
- initialize()
Initialize the statistics object, resetting all values to the state where no observations have been made. This method can, for instance, be called when the warmup period of the simulation experiment has completed.
- n()
Return the number of observations.
- Returns:
The number of observations.
- Return type:
int
- property name
Return the name of this statistics object.
- Returns:
The name of this statistics object.
- Return type:
str
- register(value: int)
The event-based classes still have a register method. This method is called by the notify method, but can also be called separately. The method processes one observation. The value indicates the increment or decrement of the counter (often 1). After processing, the method will fire updates to all listeners with the new values of the statistics.
- Parameters:
value (int) – The increment or decrement of the Counter.
- Raises:
TypeError – when value is not an int
- remove_all_listeners(event_type: EventType | None = None, listener: EventListener | None = None)
Remove an EventListener (if given) for a provided EventType (if given) for this EventProducer. It is no problem if there are no matches. There are four situations:
- event_type == None and listener == None
all listeners for all event types are removed
- event_type == None and listener is specified
the listener is removed for any event for which it was registered
- event_type is specified and listener == None
all listeners are removed for the given event_type
- event_type and listener are both specified
the listener for the given event type is removed, if it was registered; in essence this is the same as remove_listener
- Parameters:
event_type (EventType, optional) – the EventType for which this listener unsubscribes
listener (EventListener, optional) – the subscriber to remove for the provided EventType
- Raises:
EventError – if any of the arguments is of the wrong type
- remove_listener(event_type: EventType, listener: EventListener)
Remove an EventListener of this EventProducer for a given EventType. If the listener is not registered for this EventType, this will be ignored.
- Parameters:
event_type (EventType) – the EventType for which this listener unsubscribes
listener (EventListener) – the subscriber to remove for the provided Eventtype
- Raises:
EventError – if any of the arguments is of the wrong type
Return a string representing a footer for a textual table with a monospaced font that can contain multiple counters.
- classmethod report_header() str
Return a string representing a header for a textual table with a monospaced font that can contain multiple counters.
- report_line() str
Return a string representing a line with important statistics values for this counter, for a textual table with a monospaced font that can contain multiple counters.