# jp-duminy/octavius architecture

> Architecture diagram of the GitHub repository jp-duminy/octavius, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jp-duminy/octavius
- Repository: https://github.com/jp-duminy/octavius

## Overview

Octavius analyzes hydrodynamical simulation snapshots in parallel and writes HDF5 catalogues of halo and galaxy properties and particle membership. The principal workflow is configuration and snapshot reading, halo assignment and redistribution, optional 6D galaxy finding, configured property and photometry stages, then catalogue packing and writing. Users can also load catalogues and recompute selected analyses through a standalone analyser. The graph follows the documented workflow and sampled dispatch; internal links without direct call evidence are omitted.

Main entry points: [`octavius/run_octavius.py`](https://github.com/jp-duminy/octavius/blob/main/octavius/run_octavius.py) (Analysis orchestrator), [`octavius/photometry/properties_photometry.py`](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/properties_photometry.py) (Photometry stage), [`octavius/aggregate_properties/properties_core.py`](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_core.py) (Core properties), [`octavius/data_management/pack_catalogue_data.py`](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/pack_catalogue_data.py) (Catalogue packing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and distribution"]
  node_config["Configuration<br/>[conventions.py]"]
  node_reader["Snapshot readers"]
  node_readerbase["Reader base"]
  node_halo["Halo sources"]
  node_haloformats["Halo formats"]
  node_parallel["Parallel reading"]
end

subgraph group_analysis["Analysis stages"]
  node_pipeline["Stage management"]
  node_galaxy["6D galaxy finding<br/>[galaxy_finding.py]"]
  node_fof["FOF6D algorithm<br/>[fof6d_algorithm.py]"]
  node_coreprops["Core properties<br/>[properties_core.py]"]
  node_aggregate["Aggregate computations"]
  node_agghelpers["Aggregate helpers"]
  node_linking["Group linking<br/>[group_linking.py]"]
  node_localprops["Local properties"]
  node_ptypeprops["Particle-type properties"]
  node_photoprops["Photometry stage"]
  node_photocompute["Photometry computations"]
  node_photohelpers["Photometry helpers"]
  node_dust["Dust curves<br/>[dust_curves.py]"]
  node_phototable["Photometry tables"]
  node_run["Analysis orchestrator<br/>[run_octavius.py]"]
end

subgraph group_catalogue["Catalogue data"]
  node_stores["Particle and group stores<br/>[data_structures.py]"]
  node_packing["Catalogue packing"]
  node_writing["Parallel catalogue writing"]
  node_cataloguefile[("HDF5 catalogue")]
  node_version["Format version<br/>[version.py]"]
end

subgraph group_api["User analysis API"]
  node_loader["Catalogue loader<br/>[loader.py]"]
  node_analyser["Standalone analyser"]
end

node_user(("Analyst"))

node_user -->|"configures"| node_config
node_user -->|"runs analysis"| node_run
node_run -->|"builds reader"| node_reader
node_run -->|"builds halo source"| node_halo
node_halo -->|"dispatches source"| node_haloformats
node_reader -->|"uses reader base"| node_readerbase
node_run -->|"redistributes data"| node_parallel
node_run -->|"builds stores"| node_stores
node_run -->|"resolves stages"| node_pipeline
node_run -->|"finds galaxies"| node_galaxy
node_galaxy -->|"calls algorithm"| node_fof
node_run -->|"dispatches stage"| node_coreprops
node_coreprops -->|"computes quantities"| node_aggregate
node_coreprops -->|"uses helpers"| node_agghelpers
node_run -->|"dispatches stage"| node_ptypeprops
node_run -->|"dispatches stage"| node_localprops
node_run -->|"dispatches stage"| node_photoprops
node_photoprops -->|"calls computations"| node_photocompute
node_photocompute -->|"uses helpers"| node_photohelpers
node_photoprops -->|"uses attenuation"| node_dust
node_photoprops -->|"reads table"| node_phototable
node_run -->|"packs results"| node_packing
node_packing -->|"passes packed data"| node_writing
node_writing -->|"writes HDF5"| node_cataloguefile
node_user -->|"loads catalogue"| node_loader
node_cataloguefile -->|"reads catalogue"| node_loader
node_user -->|"requests subset analysis"| node_analyser
node_analyser -->|"uses catalogue API"| node_loader
node_analyser -->|"recomputes photometry"| node_photoprops
node_packing -->|"records format version"| node_version
node_linking -->|"uses helpers"| node_agghelpers

click node_config "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/conventions.py"
click node_reader "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/snapshot_readers.py"
click node_readerbase "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/snapshot_readers_base.py"
click node_halo "https://github.com/jp-duminy/octavius/blob/main/octavius/external_halo_sources/halo_data_structures.py"
click node_haloformats "https://github.com/jp-duminy/octavius/tree/main/octavius/external_halo_sources"
click node_parallel "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/parallel_reading.py"
click node_stores "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/data_structures.py"
click node_pipeline "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/pipeline_management.py"
click node_galaxy "https://github.com/jp-duminy/octavius/blob/main/octavius/galaxy_finding/galaxy_finding.py"
click node_fof "https://github.com/jp-duminy/octavius/blob/main/octavius/galaxy_finding/fof6d_algorithm.py"
click node_coreprops "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_core.py"
click node_aggregate "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/aggregate_computations.py"
click node_agghelpers "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/aggregate_helpers.py"
click node_linking "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/group_linking.py"
click node_localprops "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_local_environment.py"
click node_ptypeprops "https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_ptype_specific.py"
click node_photoprops "https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/properties_photometry.py"
click node_photocompute "https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_computations.py"
click node_photohelpers "https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_helpers.py"
click node_dust "https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/dust_curves.py"
click node_phototable "https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_tables.py"
click node_packing "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/pack_catalogue_data.py"
click node_writing "https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/parallel_writing.py"
click node_loader "https://github.com/jp-duminy/octavius/blob/main/octavius/utils/loader.py"
click node_analyser "https://github.com/jp-duminy/octavius/blob/main/octavius/utils/dynamic_analyser.py"
click node_version "https://github.com/jp-duminy/octavius/blob/main/octavius/version.py"
click node_run "https://github.com/jp-duminy/octavius/blob/main/octavius/run_octavius.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_reader,node_readerbase,node_halo,node_haloformats,node_parallel toneBlue
class node_pipeline,node_galaxy,node_fof,node_coreprops,node_aggregate,node_agghelpers,node_linking,node_localprops,node_ptypeprops,node_photoprops,node_photocompute,node_photohelpers,node_dust,node_phototable,node_run toneAmber
class node_stores,node_packing,node_writing,node_cataloguefile,node_version toneMint
class node_loader,node_analyser toneRose
class node_user toneIndigo
```

## Components

### Input and distribution

- [Configuration](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/conventions.py): `octavius/data_management/conventions.py`
- [Snapshot readers](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/snapshot_readers.py): `octavius/data_management/snapshot_readers.py`
- [Reader base](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/snapshot_readers_base.py): `octavius/data_management/snapshot_readers_base.py`
- [Halo sources](https://github.com/jp-duminy/octavius/blob/main/octavius/external_halo_sources/halo_data_structures.py): `octavius/external_halo_sources/halo_data_structures.py`
- [Halo formats](https://github.com/jp-duminy/octavius/tree/main/octavius/external_halo_sources): `octavius/external_halo_sources`
- [Parallel reading](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/parallel_reading.py): `octavius/data_management/parallel_reading.py`

### Analysis stages

- [Stage management](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/pipeline_management.py): `octavius/data_management/pipeline_management.py`
- [6D galaxy finding](https://github.com/jp-duminy/octavius/blob/main/octavius/galaxy_finding/galaxy_finding.py): `octavius/galaxy_finding/galaxy_finding.py`
- [FOF6D algorithm](https://github.com/jp-duminy/octavius/blob/main/octavius/galaxy_finding/fof6d_algorithm.py): `octavius/galaxy_finding/fof6d_algorithm.py`
- [Core properties](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_core.py): `octavius/aggregate_properties/properties_core.py`
- [Aggregate computations](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/aggregate_computations.py): `octavius/aggregate_properties/aggregate_computations.py`
- [Aggregate helpers](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/aggregate_helpers.py): `octavius/aggregate_properties/aggregate_helpers.py`
- [Group linking](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/group_linking.py): `octavius/aggregate_properties/group_linking.py`
- [Local properties](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_local_environment.py): `octavius/aggregate_properties/properties_local_environment.py`
- [Particle-type properties](https://github.com/jp-duminy/octavius/blob/main/octavius/aggregate_properties/properties_ptype_specific.py): `octavius/aggregate_properties/properties_ptype_specific.py`
- [Photometry stage](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/properties_photometry.py): `octavius/photometry/properties_photometry.py`
- [Photometry computations](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_computations.py): `octavius/photometry/photometry_computations.py`
- [Photometry helpers](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_helpers.py): `octavius/photometry/photometry_helpers.py`
- [Dust curves](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/dust_curves.py): `octavius/photometry/dust_curves.py`
- [Photometry tables](https://github.com/jp-duminy/octavius/blob/main/octavius/photometry/photometry_tables.py): `octavius/photometry/photometry_tables.py`
- [Analysis orchestrator](https://github.com/jp-duminy/octavius/blob/main/octavius/run_octavius.py): `octavius/run_octavius.py`

### Catalogue data

- [Particle and group stores](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/data_structures.py): `octavius/data_management/data_structures.py`
- [Catalogue packing](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/pack_catalogue_data.py): `octavius/data_management/pack_catalogue_data.py`
- [Parallel catalogue writing](https://github.com/jp-duminy/octavius/blob/main/octavius/data_management/parallel_writing.py): `octavius/data_management/parallel_writing.py`
- **HDF5 catalogue**
- [Format version](https://github.com/jp-duminy/octavius/blob/main/octavius/version.py): `octavius/version.py`

### User analysis API

- [Catalogue loader](https://github.com/jp-duminy/octavius/blob/main/octavius/utils/loader.py): `octavius/utils/loader.py`
- [Standalone analyser](https://github.com/jp-duminy/octavius/blob/main/octavius/utils/dynamic_analyser.py): `octavius/utils/dynamic_analyser.py`

### Other components

- **Analyst**

## Connections

- Analyst → Configuration: configures (evidence: `README.md`)
- Analyst → Analysis orchestrator: runs analysis (evidence: `README.md`)
- Analysis orchestrator → Snapshot readers: builds reader (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → Halo sources: builds halo source (evidence: `octavius/run_octavius.py`)
- Halo sources → Halo formats: dispatches source (evidence: `octavius/external_halo_sources/halo_data_structures.py`)
- Snapshot readers → Reader base: uses reader base (evidence: `octavius/data_management/snapshot_readers.py`)
- Analysis orchestrator → Parallel reading: redistributes data (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → Particle and group stores: builds stores (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → Stage management: resolves stages (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → 6D galaxy finding: finds galaxies (evidence: `octavius/run_octavius.py`)
- 6D galaxy finding → FOF6D algorithm: calls algorithm (evidence: `octavius/galaxy_finding/galaxy_finding.py`)
- Analysis orchestrator → Core properties: dispatches stage (evidence: `octavius/run_octavius.py`)
- Core properties → Aggregate computations: computes quantities (evidence: `octavius/aggregate_properties/properties_core.py`)
- Core properties → Aggregate helpers: uses helpers (evidence: `octavius/aggregate_properties/properties_core.py`)
- Analysis orchestrator → Particle-type properties: dispatches stage (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → Local properties: dispatches stage (evidence: `octavius/run_octavius.py`)
- Analysis orchestrator → Photometry stage: dispatches stage (evidence: `octavius/run_octavius.py`)
- Photometry stage → Photometry computations: calls computations (evidence: `octavius/photometry/properties_photometry.py`)
- Photometry computations → Photometry helpers: uses helpers (evidence: `octavius/photometry/photometry_computations.py`)
- Photometry stage → Dust curves: uses attenuation (evidence: `octavius/photometry/properties_photometry.py`)
- Photometry stage → Photometry tables: reads table (evidence: `octavius/photometry/properties_photometry.py`)
- Analysis orchestrator → Catalogue packing: packs results (evidence: `octavius/run_octavius.py`)
- Catalogue packing → Parallel catalogue writing: passes packed data (evidence: `octavius/data_management/parallel_writing.py`)
- Parallel catalogue writing → HDF5 catalogue: writes HDF5 (evidence: `README.md`)
- Analyst → Catalogue loader: loads catalogue (evidence: `README.md`)
- HDF5 catalogue → Catalogue loader: reads catalogue (evidence: `README.md`)
- Analyst → Standalone analyser: requests subset analysis (evidence: `README.md`)
- Standalone analyser → Catalogue loader: uses catalogue API (evidence: `octavius/utils/dynamic_analyser.py`)
- Standalone analyser → Photometry stage: recomputes photometry (evidence: `octavius/utils/dynamic_analyser.py`)
- Catalogue packing → Format version: records format version (evidence: `octavius/data_management/pack_catalogue_data.py`)
- Group linking → Aggregate helpers: uses helpers (evidence: `octavius/aggregate_properties/group_linking.py`)