weiss-sim 0.3.0

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

Weiss Schwarz Simulator

Deterministic Weiss Schwarz simulation for RL and engine research.

• Rust handles the hot loop (weiss_core)
• Python provides batched stepping (weiss_sim)
• The engine advances internally until a decision point, then exposes a stable action-space contract

Why this project

• Deterministic episodes from seed + action sequence
• Fixed, versioned observation/action encodings for training pipelines
• High-throughput EnvPool stepping for large batched RL workloads
• Replay/fingerprint metadata for drift detection and debugging

5-minute start (Python)

Option A: install from PyPI

python -m pip install -U weiss-sim numpy

Option B: local dev install (Rust + Python)

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

Minimal step loop

Use a real .wsdb path on your machine. The db_path below is a placeholder and the legal_deck ids must exist in that database.

If you are working from source, you can use the fixture DB:

db_path="python/tests/fixtures/cards.wsdb"

from pathlib import Path
import numpy as np
import weiss_sim

db_path = Path("/path/to/your/cards.wsdb")
legal_deck = (list(range(1, 14)) * 4)[:50]

pool = weiss_sim.EnvPool.new_rl_train(
    32,
    str(db_path),
    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)

For training-safe loop semantics and contract details, read docs/rl_contract.md.

Documentation

Primary docs entrypoint: docs/README.md

Recommended reading paths:

• RL users: docs/quickstart.md -> docs/rl_contract.md -> docs/encodings.md
• Python integrators: docs/python_api.md -> docs/rl_contract.md
• Engine contributors: docs/engine_architecture.md -> PROJECT_STATE.md -> docs/rules_coverage.md
• Performance work: docs/performance_benchmarks.md -> benchmark workflow in .github/workflows/benchmarks.yml

Reference links:

• Rust API docs: https://victorwp288.github.io/weiss-schwarz-simulator/rustdoc/
• Benchmark charts: https://victorwp288.github.io/weiss-schwarz-simulator/benchmarks
• Changelog: CHANGELOG.md

Benchmark Snapshot (main, top 12)

Last updated: 2026-02-16 08:36 UTC

Benchmark	Time
rust/advance_until_decision	35677 ns/iter
rust/step_batch_64	15265 ns/iter
rust/reset_batch_256	867903 ns/iter
rust/step_batch_fast_256_priority_off	74124 ns/iter
rust/step_batch_fast_256_priority_on	80038 ns/iter
rust/legal_actions	12 ns/iter
rust/legal_actions_forced	10 ns/iter
rust/on_reverse_decision_frequency_on	1162 ns/iter
rust/on_reverse_decision_frequency_off	1169 ns/iter
rust/observation_encode	178 ns/iter
rust/observation_encode_forced	183 ns/iter
rust/mask_construction	394 ns/iter

Repository layout

• weiss_core/ Rust engine core
• weiss_py/ PyO3 bindings
• python/weiss_sim/ Python API helpers and buffer wrappers
• python/examples/ benchmark and integration examples
• python/tests/ Python contract and smoke tests
• docs/ user/developer documentation hub

Local quality checks

Full CI-equivalent local parity:

scripts/run_local_ci_parity.sh
# Optional during iterative work on thermally constrained machines:
SKIP_BENCHMARKS=1 scripts/run_local_ci_parity.sh

Non-benchmark subset (useful on thermally constrained laptops):

scripts/check_env_layering.sh
python scripts/check_docs_links.py
python scripts/check_docs_constants.py
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --features test-harness
RUSTDOCFLAGS="-D missing-docs" cargo doc --workspace --no-deps
ruff format --check python scraper scripts
ruff check python scraper scripts
python scripts/ability_coverage_report.py --output /tmp/ability_coverage_report.json
python scripts/ability_coverage_targets.py --report /tmp/ability_coverage_report.json --output /tmp/ability_coverage_targets.json
python scripts/check_coverage_budget.py --report /tmp/ability_coverage_report.json --baseline scripts/ability_coverage_baseline.json --min-parse-line-coverage-strict 0.52 --max-unsupported-lines-strict 14200 --min-card-coverage-approx 0.99
maturin build --release --manifest-path weiss_py/Cargo.toml --out /tmp/wss_dist --interpreter .venv/bin/python
.venv/bin/python -m pip install --force-reinstall --no-deps /tmp/wss_dist/*.whl
.venv/bin/python -m pytest -q python/tests
cargo audit
pip-audit .
pip-audit -r scraper/requirements.txt

Compatibility and versioning

Encoding and schema values are explicit and versioned:

• OBS_ENCODING_VERSION
• ACTION_ENCODING_VERSION
• REPLAY_SCHEMA_VERSION
• WSDB_SCHEMA_VERSION

If any encoding layout changes, update:

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

License

MIT OR Apache-2.0