Coverage for moptipyapps/prodsched/statistics.py: 93%
155 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-13 02:48 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-13 02:48 +0000
1"""
2A statistics record for the simulation.
4This module provides a record with statistics derived from one single
5MFC simulation. It can store values such as the mean fill rate or the
6mean stock level.
7Such statistics records are filled in by instances of the
8:class:`~moptipyapps.prodsched.statistics_collector.StatisticsCollector`
9plugged into the
10:class:`~moptipyapps.prodsched.simulation.Simulation`.
11"""
13from itertools import chain
14from typing import Callable, Final, Generator, Iterable, Self
16from moptipy.utils.logger import KEY_VALUE_SEPARATOR
17from pycommons.io.csv import CSV_SEPARATOR, SCOPE_SEPARATOR
18from pycommons.math.stream_statistics import (
19 KEY_MAXIMUM,
20 KEY_MEAN_ARITH,
21 KEY_MINIMUM,
22 KEY_STDDEV,
23 StreamStatistics,
24)
25from pycommons.strings.string_conv import (
26 num_or_none_to_str,
27 str_to_num_or_none,
28)
29from pycommons.types import check_int_range, type_error
31#: the name of the statistics key
32COL_STAT: Final[str] = "stat"
33#: the total column name
34COL_TOTAL: Final[str] = "total"
35#: the statistics rate
36KEY_RATE: Final[str] = "rate"
37#: the product column prefix
38COL_PRODUCT_PREFIX: Final[str] = "product_"
39#: the mean TRP row
40ROW_TRP: Final[str] = "trp"
41#: the fill rate row
42ROW_SERVICE_LEVEL: Final[str] = "servicelevel"
43#: the CWT row
44ROW_CWT: Final[str] = "cwt"
45#: the mean stock level row
46ROW_STOCK_LEVEL_MEAN: Final[str] = \
47 f"stocklevel{SCOPE_SEPARATOR}{KEY_MEAN_ARITH}"
48#: the machine utilization row
49ROW_UTILIZATION_MEAN: Final[str] = \
50 f"utilization{SCOPE_SEPARATOR}{KEY_MEAN_ARITH}"
52#: the fulfilled rate
53ROW_FULFILLED_RATE: Final[str] = f"fulfilled{SCOPE_SEPARATOR}{KEY_RATE}"
54#: the simulation time getter
55ROW_SIMULATION_TIME: Final[str] = \
56 f"time{SCOPE_SEPARATOR}s{KEY_VALUE_SEPARATOR}"
58#: the keys that may need to get swapped to ensure compatibility with old
59#: versions
60_SWAP_KEYS: Final[Callable[[str, str], str]] = {
61 "fill.rate": ROW_SERVICE_LEVEL,
62 "fill": ROW_SERVICE_LEVEL,
63}.get
65#: the statistics that we will print
66_STATS: tuple[tuple[str, Callable[[
67 StreamStatistics], int | float | None]], ...] = (
68 (KEY_MINIMUM, StreamStatistics.getter_or_none(KEY_MINIMUM)),
69 (KEY_MEAN_ARITH, StreamStatistics.getter_or_none(KEY_MEAN_ARITH)),
70 (KEY_MAXIMUM, StreamStatistics.getter_or_none(KEY_MAXIMUM)),
71 (KEY_STDDEV, StreamStatistics.getter_or_none(KEY_STDDEV)))
74class Statistics:
75 """
76 A statistics record based on production scheduling.
78 It provides the following statistics:
80 - :attr:`~service_levels`: The per-product-fillrate, i.e., the fraction
81 of demands of a given product that were immediately fulfilled when
82 arriving in the system (i.e., that were fulfilled by using product that
83 was available in the warehouse/in stock).
84 Higher values are good.
85 - :attr:`~service_level`: The overall fillrate, i.e., the total fraction
86 of demands that were immediately fulfilled upon arrival in the system
87 over all demands. That is, this is the fraction of demands that were
88 fulfilled by using product that was available in the warehouse/in stock.
89 Higher values are good.
90 - :attr:`~waiting_times`: The per-product waiting times ("CWT") for the
91 demands that came in but could *not* immediately be fulfilled. These are
92 the demands for a given product that were, so to say, not covered by the
93 fillrate/:attr:`~service_level`. If all demands of a product could
94 immediately be satisfied, then this is `None`.
95 Otherwise, smaller values are good.
96 - :attr:`~waiting_time`: The overall waiting times ("CWT") for the demands
97 that came in but could *not* immediately be fulfilled. These are all the
98 demands for a given product that were, so to say, not covered by the
99 fillrate/:attr:`~service_level`. If all demands could immediately be
100 satisfied, then this is `None`.
101 Otherwise, smaller values are good.
102 - :attr:`~production_times`: The per-product times that producing one unit
103 of the product takes from the moment that a production job is created
104 until it is completed. Smaller values of this "TRP" are better.
105 - :attr:`~production_time`: The overall statistics on the times that
106 producing one unit of any product takes from the moment that a
107 production job is created until it is completed. Smaller values this
108 "TRP" are better.
109 - :attr:`~fulfilled_rates`: The per-product fraction of demands that were
110 satisfied. Demands for a product may remain unsatisfied if they have not
111 been satisfied by the end of the simulation period. Larger values are
112 better.
113 - :attr:`~fulfilled_rate`: The fraction of demands that were satisfied.
114 Demands may remain unsatisfied if they have not been satisfied by the
115 end of the simulation period. Larger values are better.
116 - :attr:`~stock_levels`: The average amount of a given product in the
117 warehouse averaged over the simulation time. Smaller values are better.
118 - :attr:`~stock_level`: The total average amount units of any product in
119 the warehouse averaged over the simulation time. Smaller values are
120 better.
121 - :attr:`~utilizations`: The average per-workstation utilization. In other
122 words, the fraction of the non-warmup simulated time that each
123 workstation was busy.
124 - :attr:`~utilization`: The total average utilization, averaged over all
125 workstations.
126 - :attr:`~simulation_time_nanos`: The total time that the simulation took,
127 measured in nanoseconds.
129 Instances of this class are filled by
130 :class:`~moptipyapps.prodsched.statistics_collector.StatisticsCollector`
131 objects plugged into the
132 :class:`~moptipyapps.prodsched.simulation.Simulation`.
133 """
135 def __init__(self, n_products: int, n_stations: int) -> None:
136 """
137 Create the statistics record for a given number of products.
139 :param n_products: the number of products
140 :param n_stations: the number of stations
141 """
142 check_int_range(n_products, "n_products", 1, 1_000_000_000)
143 check_int_range(n_stations, "n_stations", 1, 1_000_000_000)
144 #: the production time (TRP) statistics per-product
145 self.production_times: Final[list[
146 StreamStatistics | None]] = [None] * n_products
147 #: the overall production time (TRP) statistics
148 self.production_time: StreamStatistics | None = None
149 #: the fraction of demands that were immediately satisfied,
150 #: on a per-product basis, i.e., the fillrate
151 self.service_levels: Final[list[int | float | None]] = (
152 [None] * n_products)
153 #: the overall fraction of immediately satisfied demands, i.e.,
154 #: the fillrate
155 self.service_level: int | float | None = None
156 #: the average waiting time for all demands that were not immediately
157 #: satisfied -- only counting demands that were actually satisfied,
158 #: i.e., the CWT
159 self.waiting_times: Final[list[
160 StreamStatistics | None]] = [None] * n_products
161 #: the overall waiting time for all demands that were not immediately
162 #: satisfied -- only counting demands that were actually satisfied,
163 #: i.e., the CWT
164 self.waiting_time: StreamStatistics | None = None
165 #: the fraction of demands that were fulfilled, on a per-product basis
166 self.fulfilled_rates: Final[list[
167 int | float | None]] = [None] * n_products
168 #: the fraction of demands that were fulfilled overall
169 self.fulfilled_rate: int | float | None = None
170 #: the average stock level, on a per-product basis
171 self.stock_levels: Final[list[
172 int | float | None]] = [None] * n_products
173 #: the overall average stock level
174 self.stock_level: int | float | None = None
175 #: the average machine utilization, on a per-station basis
176 self.utilizations: Final[list[
177 int | float | None]] = [None] * n_stations
178 #: the overall average utilization
179 self.utilization: int | float | None = None
180 #: the nanoseconds used by the simulation
181 self.simulation_time_nanos: int | float | None = None
183 def __str__(self) -> str:
184 """Convert this object to a string."""
185 return "\n".join(to_stream(self))
187 def clear(self) -> None:
188 """Clear all the data."""
189 n: Final[int] = list.__len__(self.production_times)
190 if n <= 0:
191 raise ValueError("Huh?")
192 for i in range(n):
193 self.production_times[i] = None
194 self.service_levels[i] = None
195 self.waiting_times[i] = None
196 self.fulfilled_rates[i] = None
197 self.stock_levels[i] = None
198 for i in range(list.__len__(self.utilizations)):
199 self.utilizations[i] = None
201 self.production_time = None
202 self.service_level = None
203 self.utilization = None
204 self.waiting_time = None
205 self.fulfilled_rate = None
206 self.stock_level = None
207 self.simulation_time_nanos = None
209 def copy_from(self, stat: "Statistics") -> None:
210 """
211 Copy the contents of another statistics record.
213 :param stat: the other statistics record
214 """
215 if not isinstance(stat, Statistics):
216 raise type_error(stat, "stat", Statistics)
217 self.production_times[:] = stat.production_times
218 self.production_time = stat.production_time
219 self.service_levels[:] = stat.service_levels
220 self.service_level = stat.service_level
221 self.waiting_times[:] = stat.waiting_times
222 self.waiting_time = stat.waiting_time
223 self.fulfilled_rates[:] = stat.fulfilled_rates
224 self.fulfilled_rate = stat.fulfilled_rate
225 self.stock_levels[:] = stat.stock_levels
226 self.stock_level = stat.stock_level
227 self.simulation_time_nanos = stat.simulation_time_nanos
228 self.utilizations[:] = stat.utilizations
229 self.utilization = stat.utilization
231 def from_stream(self, stream: Iterable[str]) -> Self:
232 """
233 Load the data from a stream.
235 Notice: The `n` values of the statistics records cannot be loaded.
236 They will be lost and just set to some more or less random number.
238 :param stream: the stream of data
239 :return: this object
240 """
241 self.clear()
243 n_prod: Final[int] = list.__len__(self.production_times)
244 n_stat: Final[int] = list.__len__(self.utilizations)
245 if min(n_prod, n_stat) <= 0:
246 raise ValueError("Huh?")
248 keys: Final[set[str]] = {
249 f"{key}{SCOPE_SEPARATOR}{the_stat[0]}"
250 for key in (ROW_TRP, ROW_CWT) for the_stat in _STATS}
251 keys.update((ROW_SERVICE_LEVEL, ROW_FULFILLED_RATE,
252 ROW_STOCK_LEVEL_MEAN, ROW_UTILIZATION_MEAN))
253 sim_time_key: Final[str] = ROW_SIMULATION_TIME
255 data: dict[str, list[int | float | None]] = {}
256 sim_time: int | None = None
257 for srow in stream:
258 row = str.strip(srow)
259 if row.startswith(sim_time_key):
260 sim_time = check_int_range(
261 round(float(row[str.__len__(
262 sim_time_key):]) * 1_000_000_000),
263 sim_time_key, 0, 1_000_000_000_000_000_000_000_000)
264 if (set.__len__(keys) <= 0) or ((set.__len__(
265 keys) == 1) and (ROW_UTILIZATION_MEAN in keys)):
266 break
267 continue
269 cols: list[str] = str.split(srow, CSV_SEPARATOR)
270 key: str = cols[0]
271 key = _SWAP_KEYS(key, key)
272 if key in data:
273 raise ValueError(f"Duplicate key '{key}'.")
274 n: int = n_stat if key == ROW_UTILIZATION_MEAN else n_prod
275 if (list.__len__(cols) <= (n + 1)) or (key not in keys):
276 continue
277 data[key] = [str_to_num_or_none(cols[i]) for i in range(1, n + 2)]
278 keys.remove(key)
279 if (set.__len__(keys) <= 0) and (sim_time is not None):
280 break
282 if (set.__len__(keys) > 0) and (
283 (ROW_UTILIZATION_MEAN not in keys) or (
284 set.__len__(keys) > 1)):
285 # old versions do not support utilization, so if only this key
286 # is missing, we accept it. otherwise, there will be an error.
287 raise ValueError(f"Missing keys: {keys}")
289 if sim_time is None:
290 raise ValueError(f"Did not find key '{sim_time_key}'.")
292 self.simulation_time_nanos = sim_time
293 self.production_time = _split_data_stat(
294 data, ROW_TRP, self.production_times)
295 self.waiting_time = _split_data_stat(
296 data, ROW_CWT, self.waiting_times)
298 vals: list[int | float | None] = data[ROW_SERVICE_LEVEL]
299 self.service_level = vals[0]
300 self.service_levels[:] = vals[1:]
302 vals = data[ROW_STOCK_LEVEL_MEAN]
303 self.stock_level = vals[0]
304 self.stock_levels[:] = vals[1:]
306 vals = data[ROW_FULFILLED_RATE]
307 self.fulfilled_rate = vals[0]
308 self.fulfilled_rates[:] = vals[1:]
310 if ROW_UTILIZATION_MEAN in data:
311 vals = data[ROW_UTILIZATION_MEAN]
312 self.utilization = vals[0]
313 self.utilizations[:] = vals[1:]
315 return self
318def _split_data_stat(data: dict[str, list[int | float | None]],
319 key: str,
320 dest: list[StreamStatistics | None]) \
321 -> StreamStatistics | None:
322 """
323 Split a data set.
325 :param data: the data set
326 :param dest: the destination list
327 :return: the main statistics, if any
328 """
329 key_min: Final[str] = f"{key}{SCOPE_SEPARATOR}{KEY_MINIMUM}"
330 key_mean: Final[str] = f"{key}{SCOPE_SEPARATOR}{KEY_MEAN_ARITH}"
331 key_max: Final[str] = f"{key}{SCOPE_SEPARATOR}{KEY_MAXIMUM}"
332 key_sd: Final[str] = f"{key}{SCOPE_SEPARATOR}{KEY_STDDEV}"
333 for i in range(1, list.__len__(dest) + 1):
334 dest[i - 1] = __stream_stats(data, key_min, key_mean, key_max,
335 key_sd, i)
336 return __stream_stats(data, key_min, key_mean, key_max, key_sd, 0)
339def __stream_stats(data: dict[str, list[int | float | None]],
340 key_min: str, key_mean: str, key_max: str, key_sd: str,
341 i: int) -> StreamStatistics | None:
342 """
343 Get a stream statistics.
345 :param data: the data array
346 :param key_min: the minimum key
347 :param key_mean: the mean key
348 :param key_max: the maximum key
349 :param key_sd: the standard deviation key
350 :param i: the index
351 :return: the statistics or `None`
352 """
353 the_min = data[key_min][i]
354 the_mean = data[key_mean][i]
355 the_max = data[key_max][i]
356 the_sd = data[key_sd][i]
357 if (the_min is None) or (the_max is None):
358 return None
359 if the_mean is None:
360 raise ValueError(
361 f"Invalid mean {the_mean} for min={the_min}, max={the_max}!")
362 return StreamStatistics(n=1 if the_sd is None else 100, minimum=the_min,
363 mean_arith=the_mean,
364 maximum=the_max, stddev=the_sd)
367def to_stream(stats: Statistics) -> Generator[str, None, None]:
368 """
369 Write a statistics record to a stream.
371 :param stats: the statistics record
372 :return: the stream of data
373 """
374 n_products: Final[int] = list.__len__(stats.production_times)
375 nts: Final[Callable[[int | float | None], str]] = num_or_none_to_str
377 yield str.join(CSV_SEPARATOR, chain((
378 COL_STAT, COL_TOTAL), (f"{COL_PRODUCT_PREFIX}{i}" for i in range(
379 n_products))))
381 for key, alle, single in (
382 (ROW_TRP, stats.production_times, stats.production_time),
383 (ROW_CWT, stats.waiting_times, stats.waiting_time)):
384 for stat, call in _STATS:
385 yield str.join(CSV_SEPARATOR, chain((
386 f"{key}{SCOPE_SEPARATOR}{stat}", nts(call(single))), (
387 map(nts, map(call, alle)))))
388 yield str.join(CSV_SEPARATOR, chain((
389 ROW_SERVICE_LEVEL, nts(stats.service_level)), (
390 map(nts, stats.service_levels))))
391 yield str.join(CSV_SEPARATOR, chain((
392 ROW_STOCK_LEVEL_MEAN, nts(stats.stock_level)), (
393 map(nts, stats.stock_levels))))
394 yield str.join(CSV_SEPARATOR, chain((
395 ROW_FULFILLED_RATE, nts(stats.fulfilled_rate)), (
396 map(nts, stats.fulfilled_rates))))
397 yield str.join(CSV_SEPARATOR, chain((
398 ROW_UTILIZATION_MEAN, nts(stats.utilization)), (
399 map(nts, stats.utilizations))))
400 yield f"{ROW_SIMULATION_TIME}{nts(
401 stats.simulation_time_nanos / 1_000_000_000)}"