This document provides the API reference for the unbitrium.core module.
from unbitrium.core import SimulationEngine
The SimulationEngine orchestrates federated learning simulations, managing client selection, training coordination, and aggregation.
class SimulationEngine:
"""Orchestrates federated learning simulations.
Args:
config: Configuration dictionary.
aggregator: Aggregation algorithm.
model: Global model.
client_datasets: Dictionary of client datasets.
mode: Execution mode ('sync' or 'async').
Example:
>>> engine = SimulationEngine(
... config=config,
... aggregator=FedAvg(),
... model=global_model,
... client_datasets=datasets,
... )
>>> results = engine.run(num_rounds=10)
"""
| Method | Description |
|---|---|
run(num_rounds) |
Execute simulation for specified rounds |
select_clients(num_clients) |
Select clients for participation |
train_round() |
Execute single training round |
aggregate(updates) |
Aggregate client updates |
from unbitrium.core import EventSystem
Publish-subscribe event system for simulation lifecycle events.
class EventSystem:
"""Event management system.
Example:
>>> events = EventSystem()
>>> events.subscribe("round_end", callback_fn)
>>> events.publish("round_end", round_num=5)
"""
| Method | Description |
|---|---|
subscribe(event, callback) |
Register callback for event |
unsubscribe(event, callback) |
Remove callback |
publish(event, **kwargs) |
Trigger event with data |
clear(event) |
Clear all callbacks for event |
| Event | Data |
|---|---|
round_start |
round_num |
round_end |
round_num, metrics |
client_selected |
client_ids |
aggregation_complete |
metrics |
from unbitrium.core import ProvenanceTracker
Tracks experiment metadata for reproducibility.
class ProvenanceTracker:
"""Experiment provenance tracking.
Args:
experiment_name: Name of the experiment.
output_dir: Directory for provenance files.
Example:
>>> tracker = ProvenanceTracker("exp_001")
>>> tracker.log_config(config)
>>> tracker.log_metric("accuracy", 0.95)
>>> tracker.save_manifest()
"""
| Method | Description |
|---|---|
log_config(config) |
Log configuration |
log_metric(name, value) |
Log metric value |
log_artifact(path) |
Log artifact path |
save_manifest() |
Save provenance manifest |
load_manifest(path) |
Load existing manifest |
from unbitrium.core import RNGManager
Manages random number generators for reproducibility.
class RNGManager:
"""Deterministic random number management.
Args:
seed: Master seed for all generators.
Example:
>>> rng = RNGManager(seed=42)
>>> rng.set_all_seeds()
>>> child_rng = rng.fork(client_id=5)
"""
| Method | Description |
|---|---|
set_all_seeds() |
Set seeds for numpy, torch, random |
fork(client_id) |
Create child RNG for client |
get_state() |
Get RNG state |
set_state(state) |
Restore RNG state |
numpy_generator() |
Get numpy Generator |
torch_generator() |
Get torch Generator |
from unbitrium.core.utils import setup_logging, set_seed, create_provenance
| Function | Description |
|---|---|
setup_logging(level) |
Configure logging |
set_seed(seed) |
Set all random seeds |
create_provenance(name) |
Create provenance tracker |
from unbitrium.core.utils import setup_logging, set_seed
# Setup
setup_logging("INFO")
set_seed(42)
# Your experiment code
Last updated: January 2026