Version: 0.1.0
Domain: Complex systems
Theory seed: persistent distinctions
This repository turns a theoretical proposition into an inspectable experiment. It does not assume the proposition is true. Instead, it makes the idea concrete enough to simulate, measure, critique, and potentially reject.
What observable consequences follow when persistent distinctions are treated as an organizing principle in complex systems?
If persistent distinctions are structurally relevant, then systems organized around them should show measurable differences in persistence, failure, recovery, or robustness compared with equivalent baseline systems.
Operationalizing persistent distinctions yields no systematic difference from the baseline in the selected measurements.
Apply an explicit constraint or transformation representing persistent distinctions, then compare resulting trajectories against an otherwise equivalent baseline.
Track persistence, divergence, recovery cost, state reachability, constraint violations, and perturbation sensitivity.
The repository separates conceptual framing from executable investigation:
theory.md— theoretical foundationexperiment.md— experiment specificationproject.json— machine-readable project metadataexperiments/— executable investigations and simulation frameworkdata/— raw and generated observationsresults/— interpreted outputs
Treat this project as an executable conjecture, not a finished research result.
- Python 3.9+
pipandvenv
git clone https://github.com/standardgalactic/persistent-distinctions.git
cd persistent-distinctions
# Recommended
./scripts/manage.sh dev-install
# Manual alternative
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"Use scripts/manage.sh for day-to-day tasks:
./scripts/manage.sh help # Show all commands
./scripts/manage.sh install # Install dependencies
./scripts/manage.sh test # Run tests with coverage
./scripts/manage.sh lint # Run black/flake8/isort checks
./scripts/manage.sh format # Auto-format code
./scripts/manage.sh type-check # Run mypy
./scripts/manage.sh run # Run experiments
./scripts/manage.sh clean # Remove build/cache artifacts
./scripts/manage.sh version # Show current version
./scripts/manage.sh version-bump # Patch bump
./scripts/manage.sh version-minor # Minor bump
./scripts/manage.sh version-major # Major bump
./scripts/manage.sh release # Create release tagCore: numpy, pandas, matplotlib, scipy
Development: pytest, pytest-cov, black, flake8, isort, mypy,
sphinx
See pyproject.toml and requirements.txt for pinned versions.
The experiments package provides an extensible simulation stack:
experiments.core—SystemState,Distinction,DistinctionSetexperiments.framework— baseline/intervention comparative runner with perturbation schedulingexperiments.metrics— built-in metrics and pluggableMetricRegistryexperiments.models—BaseComplexSystemModel,SimulationResult, and runnersexperiments.protocols— typing protocols for models, metrics, perturbations, observers
from experiments.core import Distinction, DistinctionSet
from experiments.metrics import default_metric_registry
from experiments.models import run_simulation
from experiments.models.baseline import BaselineComplexSystemModel
model = BaselineComplexSystemModel(n_agents=10, n_features=3, interaction_strength=0.2, seed=42)
distinctions = DistinctionSet(
[
Distinction(
name="feature-0-invariant",
parameters={"feature_index": 0, "target_value": 0.5, "tolerance": 0.1, "min_fraction": 0.6},
)
]
)
result = run_simulation(
model,
steps=50,
distinctions=distinctions,
registry=default_metric_registry(),
)
print(len(result.trajectory), result.metric_history[-1] if result.metric_history else {})See CONTRIBUTING.md.
MIT License. See LICENSE.
This repository was scaffolded by genrepo.
Scaffolding is not evidence for the theory; it reduces the cost of converting an abstract proposition into an inspectable experimental object.