Skip to content

Getting Started

This guide takes you from installation to a validated first simulation in under 10 minutes.

  • Fast onboarding

    Install, run a baseline simulation, and confirm results with a minimal script.

  • Research-ready defaults

    Start from reproducible parameters (seed, fixed dimensions, stable layer toggles).

  • Next-step paths

    Move directly to API, configuration, and architecture depending on your role.

Prerequisites

  • Python 3.10+
  • pip

Use a virtual environment

For clean dependency management, create and activate a dedicated venv before installation.

Installation

From PyPI:

pip install policyflux

From source:

git clone https://github.com/MayoDetermined/policyflux.git
cd policyflux
pip install -e .

Optional extras:

# Neural layers
pip install -e ".[torch]"

# Text encoders
pip install -e ".[text-encoders]"

# Notebook/examples support
pip install -e ".[examples]"

# Developer tooling
pip install -e ".[dev]"

Verify installation

python -c "import policyflux; print(policyflux.__version__)"

If the command prints a version number, the package is available in your active Python environment.

Minimal simulation

from policyflux import build_engine, IntegrationConfig, LayerConfig

config = IntegrationConfig(
    num_actors=50,
    policy_dim=2,
    iterations=100,
    seed=12345,
    layer_config=LayerConfig(
        include_ideal_point=True,
        include_public_opinion=True,
        include_party_discipline=True,
        public_support=0.60,
        party_discipline_strength=0.5,
    ),
)

engine = build_engine(config)
engine.run()

print(f"Pass rate: {engine.pass_rate:.1%}")
print(f"Accepted: {engine.accepted_bills}, Rejected: {engine.rejected_bills}")

Read the first output correctly

In your first run, focus on directional interpretation, not on a specific percentage target:

  • pass_rate: overall proportion of accepted bills,
  • accepted_bills and rejected_bills: absolute outcome counts,
  • repeatability: rerun with the same seed to confirm stable behavior.

If results change with an identical script, verify that you are using the same environment and package version.

Quick comparative run (preset-based)

from policyflux import (
    build_engine,
    create_parliamentary_config,
    create_presidential_config,
)

presidential = create_presidential_config(num_actors=100, policy_dim=2, iterations=200, seed=42)
parliamentary = create_parliamentary_config(num_actors=100, policy_dim=2, iterations=200, seed=42)

eng_a = build_engine(presidential)
eng_b = build_engine(parliamentary)

eng_a.run()
eng_b.run()

print(f"Presidential pass rate: {eng_a.pass_rate:.1%}")
print(f"Parliamentary pass rate: {eng_b.pass_rate:.1%}")

This gives you a fast institutional comparison while keeping actor count, policy dimensions, iteration count, and seed constant.

First reproducibility sweep

Use a small seed sweep to estimate directional robustness:

from policyflux import build_engine, create_presidential_config

rates = []
for seed in range(10, 20):
    config = create_presidential_config(
        num_actors=100,
        policy_dim=2,
        iterations=200,
        seed=seed,
    )
    engine = build_engine(config)
    engine.run()
    rates.append(engine.pass_rate)

print(f"min={min(rates):.1%}, max={max(rates):.1%}, avg={sum(rates)/len(rates):.1%}")

Common setup issues

Import error after installation

Confirm your terminal uses the same Python interpreter where policyflux was installed.

Unstable comparisons

Keep seed fixed and change only one parameter group per experiment.

Runtime too slow

Reduce num_actors and iterations for exploratory work, then scale up.

What to inspect after run

  • engine.pass_rate
  • engine.accepted_bills
  • engine.rejected_bills

These metrics provide a baseline before adding more complex layers and actor mechanics.

Suggested next 30 minutes

  1. Read Concepts to map model assumptions.
  2. Tune one variable in Configuration.
  3. Compare two systems with Presets.
  4. Review runtime options in Engines.

Development commands

pytest
ruff check policyflux/
mypy policyflux/
mkdocs serve

Next

Choose your next path: