Reference Tables

1. Modules & Key Entrypoints

Module	Purpose	Notes
propflow.simulator.Simulator	Batch orchestration of engines over factor graphs.	Handles multiprocessing, logging, plotting.
propflow.bp.engine_base.BPEngine	Base synchronous BP engine.	Provides step routine, history tracking, convergence checks.
propflow.bp.engines	Concrete engine variants (BPEngine, DampingEngine, SplitEngine, etc.).	Mix of damping, cost reduction, splitting strategies.
propflow.utils.fg_utils.FGBuilder	Helper for constructing factor graphs.	Supports random graph generation and deterministic setups.
propflow.configs.global_config_mapping	Centralised defaults and registries.	Contains EngineDefaults, PolicyDefaults, SimulatorDefaults, CT factories, and validation helpers.
propflow.snapshots	Snapshot analyzer and reporting helpers.	Provides SnapshotAnalyzer and AnalysisReport.
propflow.snapshots.SnapshotVisualizer	Plots argmin trajectories and message norms.	Accepts in-memory snapshot lists.

2. Configuration Defaults (global_config_mapping.py)

Section	Key	Default	Meaning
Engine	max_iterations	2000	Per-run iteration cap.
Engine	normalize_messages	True	Whether to min-normalise messages post-cycle.
Engine	monitor_performance	False	Enables PerformanceMonitor.
Engine	anytime	False	Enables anytime inference updates.
Simulator	default_max_iter	5000	Default iteration cap for simulator runs.
Simulator	default_log_level	"INFORMATIVE"	Logger default verbosity.
Simulator	timeout	3600	Multiprocessing get timeout (seconds).
Policy	damping_factor	0.9	Default damping parameter.
Policy	split_factor	0.5	Weight for split engines.

Override defaults by passing explicit constructor arguments or by creating validated config dictionaries with get_validated_config().

3. CLI & Scripts

Command	Description
uv run bp-sim --version	Prints CLI version.
uv run python main.py	Runs bundled random-graph simulation demo.
uv run python examples/quick_start.py	Runs a small two-variable BP example.

4. Environment Variables

• PYTHONPATH should include src/ if you are not using editable installs.

• BP_LOG_LEVEL controls logger verbosity for the propflow.bp convenience module.

5. File & Directory Conventions

Path	Usage
configs/logs/	Default destination for simulator and engine logs.
results/	Suggested output folder for experiment artefacts (plots, JSON).
notebooks/	Exploratory analysis; keep results light-weight.
docs/handbook/	Deployment & operations documentation.

6. Glossary

• Belief: Aggregated message vector representing variable costs/probabilities.

• Argmin: Index of minimum value within a belief vector; indicates preferred assignment under Min-Sum semantics.

• Neutral Message: Message whose minimum value is not unique; indicates ties or flat preferences.

• Snapshot: Structured record of a BP iteration capturing messages, assignments, and cost metrics.

• CT Factory: Function that generates cost tables (e.g., random integers, Poisson) for factor nodes.

Use this reference as a quick lookup when working with the codebase or extending the simulator.