ideasim 0.1.0

Simulator for ideological competition dynamics -- replicator-mutator model with dormancy, hybridization, and endogenous environment modification

ideasim

A simulator for ideological competition dynamics over historical timescales. Models how ideological currents compete, spread, go dormant, and re-emerge using replicator-mutator dynamics with dormancy, hybridization, and endogenous environment modification. The full system is a Piecewise Deterministic Markov Process (PDMP).

Quick Start

pip install ideasim

Run the default scenario (Europe 1800-2025):

ideasim simulate -o results.json

Export and edit the default configuration:

ideasim default-config -o my_config.json
# edit my_config.json ...
ideasim simulate my_config.json -o results.json

What It Models

ideasim simulates how ideological currents (liberalism, Marxism, traditionalism, nationalism, and their hybrids) evolve over time. The model captures:

• Manifest adoption (x): observable adherence to ideologies on the simplex.
• Latent sympathy (y): hidden reservoirs of support that enable dormancy and re-emergence (the "martyrdom effect").
• Environment (e): exogenous conditions (GDP growth, inequality, media freedom, social media penetration, conflict) that shape ideological fitness.
• Stochastic events: hybridization (new ideologies from blending two parents), charismatic bursts, and parameter mutation.

For the full mathematical framework, see the paper/ directory or the documentation.

Installation

From PyPI

pip install ideasim

From source (development)

git clone https://github.com/LeonardoSanBenitez/ideasim.git
cd ideasim
pip install -e ".[dev]"

Docker

docker compose build
docker compose run --rm simulator

Usage

Python API

from ideasim.defaults import load_default_config
from ideasim.engine import simulate

config = load_default_config()
result = simulate(config, seed=42)

print(f"Final shares: {result.final_shares}")
print(f"Events triggered: {len(result.events)}")

CLI

# Run with default parameters
ideasim simulate -o results.json

# Custom config
ideasim simulate my_config.json -o results.json

# Export default config for editing
ideasim default-config -o default_config.json

Running Tests

python -m pytest tests/ -v

Project Structure

ideasim/
    ideasim/             # Python package
        types.py         # Core data types (Ideology, SimulationConfig, etc.)
        engine.py        # PDMP simulation engine (RK4 + stochastic events)
        defaults.py      # Loads default scenario from JSON data file
        io.py            # JSON serialization/deserialization
        cli.py           # Command-line interface
        sensitivity.py   # Sensitivity analysis (OAT + LHS)
        validation.py    # Input validation
        health.py        # Health checks
        evaluation/      # Validation against observed data (ParlGov)
        data/
            default_scenario.json
    tests/               # Test suite (104 tests)
    paper/               # LaTeX paper
    scripts/             # Shell scripts for Docker workflows

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for guidelines on setting up the development environment, running tests, and submitting pull requests.

Citation

If you use ideasim in your research, please cite:

@software{ideasim,
  title = {ideasim: Ideological Dynamics Simulator},
  author = {San Benitez, Leonardo},
  year = {2026},
  url = {https://github.com/LeonardoSanBenitez/ideasim},
}

License

Apache License 2.0. See LICENSE for details.