Skip to content

Getting started

Install latest stable release

To install vote_simulation, run this command in your terminal:

uv add vote_simulation

Or if you prefer to use pip:

pip install vote_simulation

From source

The source files for vote_simulation can be downloaded from the Github repo.

You can also clone the public repository:

git clone https://github.com/Ambraser/vote-simulation

Once you have a copy of the source, you can install it with:

cd vote_simulation
uv sync

The typical workflow is:

  1. prepare a TOML config file,
  2. run the simulation (data generation is handled automatically),
  3. inspect the results.

The default example config lives in config/simulation.toml.

TOML config file

[simulation]
output_base_path = "data"
generative_models = ["VMF_HC"]
rule_codes = ["PLU1", "BORD", "SCHU"]
candidates = [3, 14]
voters = [11, 101]
iterations = 10
seed = 42

Copy this into a simulation.toml file and adjust as needed.

Run the pipeline

from vote_simulation.simulation.simulation import simulation_from_config

simulation_from_config("config/simulation.toml")

Output structure

The pipeline writes files with this structure:

data/
├── gen/
│   └── <MODEL>_v<VOTERS>_c<CANDIDATES>/
│       ├── iter_0001.parquet
│       └── ...
├── sim_result/
│   └── <MODEL>_v<VOTERS>_c<CANDIDATES>/
│       ├── iter_0001.parquet
│       └── ...
└── results/
    └── <MODEL>_v<VOTERS>_c<CANDIDATES>.parquet   ← series cache