weiss-sim 0.8.0

Deterministic Weiss Schwarz simulator with a Rust core and Python bindings.

Weiss Schwarz Simulator

Deterministic Weiss Schwarz simulation for RL and engine research.

What you get

• Rust engine (weiss_core) with deterministic advance-until-decision stepping
• PyO3 bindings (weiss_py) and Python API (python/weiss_sim) for batched training/eval loops
• Stable observation/action contracts (OBS_LEN=378, ACTION_SPACE_SIZE=527, SPEC_HASH=8590000130)
• Replay and fingerprint surfaces for drift detection and reproducibility

5-minute start

Option A: install from PyPI

python -m pip install -U weiss-sim numpy

Option B: local build from source

python -m pip install -U maturin numpy
python -m maturin develop --release --manifest-path weiss_py/Cargo.toml

Run the commands in the Python environment where you want weiss_sim installed. If you are using a virtualenv, activate it first.

Option C: contributor setup (dev extras + local extension)

rustup component add rustfmt clippy
python -m venv .venv
# activate the virtualenv before the next commands
# PowerShell: .\.venv\Scripts\Activate.ps1
# Bash / zsh: source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m maturin develop --release --manifest-path weiss_py/Cargo.toml

This installs .[dev] extras (ruff, pytest, maturin, pip-audit) and builds the local extension in-place.

Virtualenv activation examples:

• PowerShell: .\.venv\Scripts\Activate.ps1
• Bash / zsh: source .venv/bin/activate

If you prefer the helper script, scripts/setup_dev_env.sh runs the same install flow in Bash-compatible shells.

Minimal high-level loop

import numpy as np
import weiss_sim

with weiss_sim.fast(num_envs=32, seed=0) as sim:
    reset = sim.reset()
    actions = reset.legal.sample_uniform(seed=123)
    step = sim.step(actions)

Minimal low-level loop

import numpy as np
import weiss_sim

legal_deck = (list(range(1, 14)) * 4)[:50]

pool = weiss_sim.EnvPool.new_rl_train(
    32,
    deck_lists=[legal_deck, legal_deck],
    deck_ids=[1, 2],
    seed=0,
)
buf = weiss_sim.EnvPoolBuffers(pool)
out = buf.reset()
actions = np.full(pool.envs_len, weiss_sim.PASS_ACTION_ID, dtype=np.uint32)
out = buf.step(actions)

Deck authoring flow (Python)

import weiss_sim

builder = weiss_sim.cards.builder(initial="starter_v1")
builder.set_count("CARD-1", 4)
report = builder.validate(rules_profile="approx", card_pool="all")
if report.ok:
    deck_ids = builder.build(rules_profile="approx", card_pool="all")

Architecture at a glance

flowchart LR
  A["Python API\npython/weiss_sim"] --> B["PyO3 bindings\nweiss_py"]
  B --> C["Engine core\nweiss_core"]
  C --> D["Deterministic outputs\nobs/masks-or-ids/reward/status"]
  C --> E["Replay + fingerprint\nrepro & drift debugging"]

Documentation map

Start in docs/README.md.

Recommended paths:

• New users: docs/beginner_happy_path.md -> docs/quickstart.md -> docs/how_it_works.md
• RL users: docs/quickstart.md -> docs/tutorials/ppo.md -> docs/rl_contract.md -> docs/encodings.md
• Off-policy users: docs/tutorials/impala_vtrace.md -> docs/rl_contract.md
• Python integrators: docs/python_api.md -> docs/python_api_reference.md -> docs/troubleshooting.md
• Engine contributors: docs/engine_architecture.md -> docs/rules_coverage.md -> PROJECT_STATE.md
• Performance work: docs/performance_benchmarks.md

Repository layout

• weiss_core/: Rust engine and deterministic rule runtime
• weiss_py/: PyO3 extension layer
• python/weiss_sim/: high-level and low-level Python interfaces
• python/tests/: Python API/contract tests
• scripts/: CI parity, coverage, perf, and docs checks
• docs/: user + contributor documentation hub

Local quality checks

Full local CI parity:

bash scripts/run_local_ci_parity.sh

On Windows, run the underlying commands directly from PowerShell:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
python -m ruff format --check python scraper scripts
python -m ruff check python scraper scripts
python scripts/check_docs_links.py
python scripts/check_docs_constants.py
python scripts/gen_docs_snippets.py --check
python -m pytest -q python/tests

Skip benchmark gate during iteration:

SKIP_BENCHMARKS=1 bash scripts/run_local_ci_parity.sh

Docs-only checks:

python scripts/check_docs_links.py
python scripts/check_docs_constants.py
python scripts/gen_docs_snippets.py --check

Benchmark snapshot (main)

Last updated: 2026-04-20 09:50 UTC

Benchmark	Time
rust/advance_until_decision	46132 ns/iter
rust/step_batch_64	15603 ns/iter
rust/reset_batch_256	860159 ns/iter
rust/step_batch_fast_256_priority_off	87326 ns/iter
rust/step_batch_fast_256_priority_on	87674 ns/iter
rust/legal_actions	11 ns/iter
rust/legal_actions_forced	11 ns/iter
rust/on_reverse_decision_frequency_on	1458 ns/iter
rust/on_reverse_decision_frequency_off	1425 ns/iter
rust/observation_encode	182 ns/iter
rust/observation_encode_forced	181 ns/iter
rust/mask_construction	297 ns/iter

Long-form benchmark docs: docs/performance_benchmarks.md

Compatibility policy

Contract constants are explicit compatibility boundaries:

• OBS_ENCODING_VERSION=2
• ACTION_ENCODING_VERSION=1
• POLICY_VERSION=2
• REPLAY_SCHEMA_VERSION=2
• WSDB_SCHEMA_VERSION=2

If encoding/layout semantics change, update code + docs in the same PR:

1. constants/encode implementation
2. docs/rl_contract.md checksum table
3. docs/encodings_changelog.md

License

MIT OR Apache-2.0