Architecture

A map of src/clocks for anyone reading or extending the code — a C4-inspired module map (modules grouped into functional clusters), not a formal C4 component diagram. Solid arrows mean “imports from”; dashed arrows show executable dispatch. Re-exports inside clocks/__init__.py are omitted.

flowchart TB
    subgraph contracts["Validation and data contracts"]
        validation["_validation"]
        types
        config
        results
    end
    subgraph physnoise["Physics and noise"]
        physics
        noise
        support["_support"]
    end
    subgraph core["Inference and public API"]
        inference
        api
    end
    subgraph vis["Visualization"]
        viz
        animate["_animate"]
        panels["_panels"]
        panels3d["_panels3d"]
    end
    subgraph scenarios["Scenario tooling"]
        scenario["_scenarios"]
        echo["_echo_study"]
    end
    subgraph entry["Packaged entry points"]
        demos["_demos/*"]
    end
    console["uv run demo-*"]
    wrappers["scripts/demo_*.py"]

    types --> validation
    config --> validation
    config --> types
    results --> validation
    results --> config
    results --> types
    physics --> validation
    physics --> types
    support --> physics
    support --> types
    inference --> validation
    inference --> types
    api --> support
    api --> config
    api --> inference
    api --> noise
    api --> physics
    api --> results
    viz --> animate
    viz --> panels
    viz --> panels3d
    animate --> inference
    animate --> physics
    animate --> panels
    animate --> panels3d
    scenario --> support
    scenario --> api
    scenario --> inference
    scenario --> physics
    echo --> scenario
    echo --> physics
    demos --> api
    demos --> scenario
    demos --> viz
    console -. "pyproject entry points" .-> demos
    wrappers -. "thin imports" .-> demos

In words (text equivalent of the diagram): _validation, types, and config establish immutable public contracts. physics implements strict weak-field forward models; _support defines the conditional prior support used before those strict models are called. inference implements adaptive tempered resample-move SMC, and api connects it to configuration, simulation, physics, noise, and result objects. viz is the public facade over private animation and panel modules. _scenarios and _echo_study provide shared builders and reporting for demos, scans, and tests.

The seven [project.scripts] entries in pyproject.toml point directly to main() functions under clocks._demos. Those packaged modules contain the implementations and select Matplotlib’s headless backend before importing pyplot. Repository files under scripts/demo_*.py are only convenience wrappers importing the corresponding packaged main(); an installed wheel does not depend on the repository’s scripts/ directory.

The public/private boundary

The package’s promised surface is the set of names curated in clocks/__init__.py::__all__ — the API entry points, configuration and result dataclasses, core types, and selected physics, noise, inference, and visualization names. Entire modules are not the promised surface. Modules whose names begin with an underscore, including _support, _scenarios, _echo_study, and _demos, are internal; library callers should import from clocks directly.