Utils Module

Helper functions and configuration utilities.

Configuration

Configuration loading from YAML and JSON files.

class simcraft.utils.config.ConfigLoader[source]

Bases: object

Load configuration from various file formats.

Examples

>>> config = ConfigLoader.load("config.yaml")
>>> print(config["simulation"]["duration"])

static load(filepath)[source]

Load configuration from file.

Supports .yaml, .yml, and .json files.

Parameters:: filepath (str) – Path to configuration file
Returns:: Configuration dictionary
Return type:: Dict[str, Any]

static save(config, filepath)[source]

Save configuration to file.

Parameters:

config (Dict[str, Any]) – Configuration dictionary
filepath (str) – Output path

Return type:

None

class simcraft.utils.config.YAMLConfig[source]

Bases: object

Base class for typed configuration.

Subclass this to create strongly-typed configuration classes.

Examples

>>> @dataclass
... class SimConfig(YAMLConfig):
...     duration: float = 100.0
...     warmup: float = 10.0
...     seed: int = 42
...
>>> config = SimConfig.from_file("config.yaml")
>>> print(config.duration)

classmethod from_dict(data)[source]

Create instance from dictionary.

Parameters:: data (Dict[str, Any]) – Configuration data
Returns:: Configuration instance
Return type:: T

classmethod from_file(filepath)[source]

Create instance from file.

Parameters:: filepath (str) – Configuration file path
Returns:: Configuration instance
Return type:: T

to_dict()[source]

Convert to dictionary.

Returns:: Configuration dictionary
Return type:: Dict[str, Any]

save(filepath)[source]

Save to file.

Parameters:: filepath (str) – Output path
Return type:: None

__init__()

Return type:: None

class simcraft.utils.config.SimulationConfig[source]

Bases: YAMLConfig

Standard simulation configuration.

name

Simulation name

Type:: str

duration

Total simulation time

Type:: float

warmup

Warmup period

Type:: float

seed

Random seed

Type:: int

replications

Number of replications

Type:: int

time_unit

Time unit (hours, minutes, etc.)

Type:: str

name: str = 'Simulation'

duration: float = 100.0

warmup: float = 0.0

seed: int | None = None

replications: int = 1

time_unit: str = 'hours'

log_level: str = 'WARNING'

collect_trace: bool = False

__init__(name='Simulation', duration=100.0, warmup=0.0, seed=None, replications=1, time_unit='hours', log_level='WARNING', collect_trace=False)

Parameters:

name (str)
duration (float)
warmup (float)
seed (int | None)
replications (int)
time_unit (str)
log_level (str)
collect_trace (bool)

Return type:

None

Logging

Structured logging for simulations.

class simcraft.utils.logging.SimulationLogger[source]

Bases: object

Logger for simulation events.

Provides structured logging with simulation time stamps.

Parameters:

sim (Simulation) – Parent simulation
name (str) – Logger name
level (int) – Logging level

Examples

>>> logger = SimulationLogger(sim, "MyModel")
>>> logger.info("Customer arrived")
>>> logger.debug("Queue length: %d", queue.length)

__init__(sim, name='', level=20)[source]

Initialize logger.

Parameters:

sim (Simulation)
name (str)
level (int)

Return type:

None

debug(message, *args, **kwargs)[source]

Log debug message.

Parameters:

message (str)
args (Any)
kwargs (Any)

Return type:

None

info(message, *args, **kwargs)[source]

Log info message.

Parameters:

message (str)
args (Any)
kwargs (Any)

Return type:

None

warning(message, *args, **kwargs)[source]

Log warning message.

Parameters:

message (str)
args (Any)
kwargs (Any)

Return type:

None

error(message, *args, **kwargs)[source]

Log error message.

Parameters:

message (str)
args (Any)
kwargs (Any)

Return type:

None

event(event_type, entity_id=None, **details)[source]

Log a structured simulation event.

Parameters:

event_type (str) – Type of event (e.g., “arrival”, “departure”)
entity_id (Optional[str]) – Entity identifier
**details – Additional event details

Return type:

None

set_level(level)[source]

Set logging level.

Parameters:: level (int)
Return type:: None

simcraft.utils.logging.setup_logging(level=20, format_string=None, filename=None)[source]

Set up logging for simulation.

Parameters:

level (int) – Logging level
format_string (Optional[str]) – Custom format string
filename (Optional[str]) – Log file path

Return type:

None

Visualization

Plotting utilities for simulation output.

simcraft.utils.visualization.plot_time_series(time_series, title=None, xlabel='Time', ylabel='Value', figsize=(10, 6), show=True, save_path=None)[source]

Plot a time series.

Parameters:

time_series (TimeSeries) – Time series to plot
title (Optional[str]) – Plot title
xlabel (str) – X-axis label
ylabel (str) – Y-axis label
figsize (Tuple[int, int]) – Figure size
show (bool) – Whether to show the plot
save_path (Optional[str]) – Path to save figure

Returns:

Matplotlib figure

Return type:

Any

simcraft.utils.visualization.plot_histogram(tally, bins=20, title=None, xlabel='Value', ylabel='Frequency', figsize=(10, 6), show=True, save_path=None)[source]

Plot histogram from tally data.

Parameters:

tally (Tally) – Tally with history
bins (int) – Number of bins
title (Optional[str]) – Plot title
xlabel (str) – X-axis label
ylabel (str) – Y-axis label
figsize (Tuple[int, int]) – Figure size
show (bool) – Whether to show plot
save_path (Optional[str]) – Path to save figure

Returns:

Matplotlib figure

Return type:

Any