Sovereign 8s.is mirror of standardgalactic/persistent-distinctions
  • Python 72.7%
  • Jupyter Notebook 18.9%
  • Shell 8.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-09 00:07:41 -03:00
.github Complete scientific Python research infrastructure setup 2026-08-07 05:31:07 -03:00
benchmarks Add benchmark suite for performance and accuracy testing 2026-08-07 06:11:48 -03:00
data Add data directory README 2026-08-07 05:28:24 -03:00
examples Add example scripts demonstrating framework usage 2026-08-07 06:15:01 -03:00
experiments Implement meaningful comparative experiment output 2026-08-09 03:03:24 +00:00
notebooks Add interactive research notebooks 2026-08-07 18:20:52 +00:00
notes Add comprehensive research notes on framework, hypotheses, and theoretical foundations 2026-08-07 06:21:57 -03:00
papers Add papers directory for publications and manuscripts 2026-08-07 05:28:16 -03:00
reproducibility Add reproducibility manifest with seeds, hashes, and experiment parameters 2026-08-07 06:17:31 -03:00
results Apply remaining changes 2026-08-07 09:29:21 +00:00
scripts Update project name reference in manage.sh script 2026-08-07 06:09:21 -03:00
tests Add comparative research framework and metrics 2026-08-07 08:48:02 +00:00
.editorconfig Add project management infrastructure and configuration files 2026-08-07 05:20:17 -03:00
.gitattributes Add .gitattributes for consistent line endings 2026-08-07 05:28:50 -03:00
.gitignore Add project management infrastructure and configuration files 2026-08-07 05:20:17 -03:00
.pre-commit-config.yaml Add pre-commit hooks for automated code quality checks 2026-08-07 05:27:30 -03:00
.python-version Add .python-version specification 2026-08-07 05:18:02 -03:00
CHANGELOG.md Add CHANGELOG tracking project updates 2026-08-07 05:21:07 -03:00
CITATION.cff Add CITATION.cff for research software citation 2026-08-07 05:27:13 -03:00
conftest.py Add pytest configuration and fixtures 2026-08-07 05:28:43 -03:00
CONTRIBUTING.md Add CONTRIBUTING guidelines 2026-08-07 05:32:34 -03:00
experiment.md Initial theoretical experiment 2026-08-06 19:16:22 -03:00
LICENSE Add MIT License 2026-08-07 05:18:09 -03:00
MANIFEST.in Add MANIFEST.in for source distribution 2026-08-07 05:28:33 -03:00
project.json Initial theoretical experiment 2026-08-06 19:16:22 -03:00
pyproject.toml Add project management infrastructure and configuration files 2026-08-07 05:20:17 -03:00
pytest.ini Add pytest.ini configuration 2026-08-07 05:28:08 -03:00
README.md Clean up README language and structure 2026-08-09 03:01:39 +00:00
requirements.txt Add project configuration and requirements files 2026-08-07 05:34:18 -03:00
ROADMAP.md Add research roadmap documenting theoretical and experimental agenda 2026-08-07 05:27:52 -03:00
run.sh Make run.sh robust and module-based 2026-08-09 03:04:23 +00:00
setup.py Add setup.py for package installation 2026-08-07 05:17:55 -03:00
theory.md Initial theoretical experiment 2026-08-06 19:16:22 -03:00
tox.ini Complete scientific Python research infrastructure setup 2026-08-07 05:31:07 -03:00

Persistent Distinctions

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.

Research framing

Research question

What observable consequences follow when persistent distinctions are treated as an organizing principle in complex systems?

Working hypothesis

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.

Null hypothesis

Operationalizing persistent distinctions yields no systematic difference from the baseline in the selected measurements.

Operationalization

Apply an explicit constraint or transformation representing persistent distinctions, then compare resulting trajectories against an otherwise equivalent baseline.

Measurements

Track persistence, divergence, recovery cost, state reachability, constraint violations, and perturbation sensitivity.

Repository structure

The repository separates conceptual framing from executable investigation:

  • theory.md — theoretical foundation
  • experiment.md — experiment specification
  • project.json — machine-readable project metadata
  • experiments/ — executable investigations and simulation framework
  • data/ — raw and generated observations
  • results/ — interpreted outputs

Treat this project as an executable conjecture, not a finished research result.

Quick start

Prerequisites

  • Python 3.9+
  • pip and venv

Setup

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]"

Common commands

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 tag

Dependencies

Core: numpy, pandas, matplotlib, scipy
Development: pytest, pytest-cov, black, flake8, isort, mypy, sphinx

See pyproject.toml and requirements.txt for pinned versions.

Core research framework

The experiments package provides an extensible simulation stack:

  • experiments.core — SystemState, Distinction, DistinctionSet
  • experiments.framework — baseline/intervention comparative runner with perturbation scheduling
  • experiments.metrics — built-in metrics and pluggable MetricRegistry
  • experiments.models — BaseComplexSystemModel, SimulationResult, and runners
  • experiments.protocols — typing protocols for models, metrics, perturbations, observers

Example usage

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 {})

Contributing

See CONTRIBUTING.md.

License

MIT License. See LICENSE.

Project origin

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.