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

1""" 

2A statistics record for the simulation. 

3 

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""" 

12 

13from itertools import chain 

14from typing import Callable, Final, Generator, Iterable, Self 

15 

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 

30 

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}" 

51 

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}" 

57 

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 

64 

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))) 

72 

73 

74class Statistics: 

75 """ 

76 A statistics record based on production scheduling. 

77 

78 It provides the following statistics: 

79 

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. 

128 

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 """ 

134 

135 def __init__(self, n_products: int, n_stations: int) -> None: 

136 """ 

137 Create the statistics record for a given number of products. 

138 

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 

182 

183 def __str__(self) -> str: 

184 """Convert this object to a string.""" 

185 return "\n".join(to_stream(self)) 

186 

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 

200 

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 

208 

209 def copy_from(self, stat: "Statistics") -> None: 

210 """ 

211 Copy the contents of another statistics record. 

212 

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 

230 

231 def from_stream(self, stream: Iterable[str]) -> Self: 

232 """ 

233 Load the data from a stream. 

234 

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. 

237 

238 :param stream: the stream of data 

239 :return: this object 

240 """ 

241 self.clear() 

242 

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?") 

247 

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 

254 

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 

268 

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 

281 

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}") 

288 

289 if sim_time is None: 

290 raise ValueError(f"Did not find key '{sim_time_key}'.") 

291 

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) 

297 

298 vals: list[int | float | None] = data[ROW_SERVICE_LEVEL] 

299 self.service_level = vals[0] 

300 self.service_levels[:] = vals[1:] 

301 

302 vals = data[ROW_STOCK_LEVEL_MEAN] 

303 self.stock_level = vals[0] 

304 self.stock_levels[:] = vals[1:] 

305 

306 vals = data[ROW_FULFILLED_RATE] 

307 self.fulfilled_rate = vals[0] 

308 self.fulfilled_rates[:] = vals[1:] 

309 

310 if ROW_UTILIZATION_MEAN in data: 

311 vals = data[ROW_UTILIZATION_MEAN] 

312 self.utilization = vals[0] 

313 self.utilizations[:] = vals[1:] 

314 

315 return self 

316 

317 

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. 

324 

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) 

337 

338 

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. 

344 

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) 

365 

366 

367def to_stream(stats: Statistics) -> Generator[str, None, None]: 

368 """ 

369 Write a statistics record to a stream. 

370 

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 

376 

377 yield str.join(CSV_SEPARATOR, chain(( 

378 COL_STAT, COL_TOTAL), (f"{COL_PRODUCT_PREFIX}{i}" for i in range( 

379 n_products)))) 

380 

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)}"