# osyris-project/osyris architecture

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

- Interactive diagram: https://gitdiagram.com/osyris-project/osyris
- Repository: https://github.com/osyris-project/osyris

## Overview

Osyris is a Python utility for loading RAMSES astrophysical simulation data, exploring it with unit-aware data structures and spatial selections, and producing scientific visualizations. The main workflow loads a selected simulation output into grouped data, then passes fields or layers to histogram or map plotting and returns a plot result. The map implementation shows projection, binning, and rendering; other plotting internals and the dataset-loading entry point were not sampled, so those links are limited to documented behavior and visible module boundaries.

Main entry points: [`src/osyris/io/loader.py`](https://github.com/osyris-project/osyris/blob/main/src/osyris/io/loader.py) (Output loader), [`src/osyris/core/dataset.py`](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/dataset.py) (Dataset groups), [`src/osyris/plot/hist2d.py`](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/hist2d.py) (Histograms), [`src/osyris/plot/map.py`](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/map.py) (Maps and projection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_loading["RAMSES loading"]
  node_ramses["RamsesDataset<br/>[ramses.py]"]
  node_loader["Output loader<br/>[loader.py]"]
  node_readers["Format readers<br/>[reader.py]"]
  node_amr["AMR and Hilbert<br/>[hilbert.py]"]
end

subgraph group_data["Data and units"]
  node_dataset["Dataset groups<br/>[dataset.py]"]
  node_datagroup["Datagroup fields<br/>[datagroup.py]"]
  node_array["Unit-aware arrays<br/>[array.py]"]
  node_vector["Vectors<br/>[vector.py]"]
  node_config["Derived variables<br/>[defaults.py]"]
  node_units["Units<br/>[units.py]"]
end

subgraph group_analysis["Spatial analysis"]
  node_spatial["Subdomain extraction<br/>[subdomain.py]"]
end

subgraph group_viz["Visualization"]
  node_layers["Plot layers<br/>[layer.py]"]
  node_hist["Histograms<br/>[hist2d.py]"]
  node_map["Maps and projection<br/>[map.py]"]
  node_parser["Layer parsing<br/>[parser.py]"]
  node_render["Rendering<br/>[render.py]"]
  node_plotresult["Plot result<br/>[plot.py]"]
end

node_user(("Researcher"))
node_files["RAMSES output"]

node_user -->|"requests load"| node_ramses
node_files -->|"reads output"| node_loader
node_ramses -->|"loads output"| node_loader
node_loader -->|"dispatches reads"| node_readers
node_loader -->|"selects CPU domains"| node_amr
node_loader -->|"assembles groups"| node_dataset
node_readers -->|"provides fields"| node_dataset
node_dataset -->|"holds groups"| node_datagroup
node_datagroup -->|"holds fields"| node_array
node_array -->|"converts units"| node_units
node_vector -->|"wraps components"| node_array
node_config -->|"adds derived fields"| node_dataset
node_user -->|"selects region"| node_spatial
node_spatial -->|"returns subset"| node_dataset
node_user -->|"requests histogram"| node_hist
node_user -->|"requests map"| node_map
node_hist -->|"parses layers"| node_parser
node_map -->|"parses layers"| node_parser
node_map -->|"renders projection"| node_render
node_hist -->|"renders histogram"| node_render
node_render -->|"returns figure"| node_plotresult
node_user -->|"configures fields"| node_layers

click node_ramses "https://github.com/osyris-project/osyris/blob/main/src/osyris/io/ramses.py"
click node_loader "https://github.com/osyris-project/osyris/blob/main/src/osyris/io/loader.py"
click node_readers "https://github.com/osyris-project/osyris/blob/main/src/osyris/io/reader.py"
click node_amr "https://github.com/osyris-project/osyris/blob/main/src/osyris/io/hilbert.py"
click node_dataset "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/dataset.py"
click node_datagroup "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/datagroup.py"
click node_array "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/array.py"
click node_vector "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/vector.py"
click node_config "https://github.com/osyris-project/osyris/blob/main/src/osyris/config/defaults.py"
click node_units "https://github.com/osyris-project/osyris/blob/main/src/osyris/units/units.py"
click node_spatial "https://github.com/osyris-project/osyris/blob/main/src/osyris/spatial/subdomain.py"
click node_layers "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/layer.py"
click node_hist "https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/hist2d.py"
click node_map "https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/map.py"
click node_parser "https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/parser.py"
click node_render "https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/render.py"
click node_plotresult "https://github.com/osyris-project/osyris/blob/main/src/osyris/core/plot.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_ramses,node_loader,node_readers,node_amr toneBlue
class node_dataset,node_datagroup,node_array,node_vector,node_config,node_units toneAmber
class node_spatial toneMint
class node_layers,node_hist,node_map,node_parser,node_render,node_plotresult toneRose
class node_user,node_files toneIndigo
```

## Components

### RAMSES loading

- [RamsesDataset](https://github.com/osyris-project/osyris/blob/main/src/osyris/io/ramses.py): `src/osyris/io/ramses.py`
- [Output loader](https://github.com/osyris-project/osyris/blob/main/src/osyris/io/loader.py): `src/osyris/io/loader.py`
- [Format readers](https://github.com/osyris-project/osyris/blob/main/src/osyris/io/reader.py): `src/osyris/io/reader.py`
- [AMR and Hilbert](https://github.com/osyris-project/osyris/blob/main/src/osyris/io/hilbert.py): `src/osyris/io/hilbert.py`

### Data and units

- [Dataset groups](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/dataset.py): `src/osyris/core/dataset.py`
- [Datagroup fields](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/datagroup.py): `src/osyris/core/datagroup.py`
- [Unit-aware arrays](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/array.py): `src/osyris/core/array.py`
- [Vectors](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/vector.py): `src/osyris/core/vector.py`
- [Derived variables](https://github.com/osyris-project/osyris/blob/main/src/osyris/config/defaults.py): `src/osyris/config/defaults.py`
- [Units](https://github.com/osyris-project/osyris/blob/main/src/osyris/units/units.py): `src/osyris/units/units.py`

### Spatial analysis

- [Subdomain extraction](https://github.com/osyris-project/osyris/blob/main/src/osyris/spatial/subdomain.py): `src/osyris/spatial/subdomain.py`

### Visualization

- [Plot layers](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/layer.py): `src/osyris/core/layer.py`
- [Histograms](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/hist2d.py): `src/osyris/plot/hist2d.py`
- [Maps and projection](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/map.py): `src/osyris/plot/map.py`
- [Layer parsing](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/parser.py): `src/osyris/plot/parser.py`
- [Rendering](https://github.com/osyris-project/osyris/blob/main/src/osyris/plot/render.py): `src/osyris/plot/render.py`
- [Plot result](https://github.com/osyris-project/osyris/blob/main/src/osyris/core/plot.py): `src/osyris/core/plot.py`

### Other components

- **Researcher**
- **RAMSES output**

## Connections

- Researcher → RamsesDataset: requests load
- RAMSES output → Output loader: reads output
- RamsesDataset → Output loader: loads output
- Output loader → Format readers: dispatches reads
- Output loader → AMR and Hilbert: selects CPU domains
- Output loader → Dataset groups: assembles groups
- Format readers → Dataset groups: provides fields
- Dataset groups → Datagroup fields: holds groups
- Datagroup fields → Unit-aware arrays: holds fields
- Unit-aware arrays → Units: converts units
- Vectors → Unit-aware arrays: wraps components
- Derived variables → Dataset groups: adds derived fields
- Researcher → Subdomain extraction: selects region
- Subdomain extraction → Dataset groups: returns subset
- Researcher → Histograms: requests histogram
- Researcher → Maps and projection: requests map
- Histograms → Layer parsing: parses layers
- Maps and projection → Layer parsing: parses layers
- Maps and projection → Rendering: renders projection
- Histograms → Rendering: renders histogram
- Rendering → Plot result: returns figure
- Researcher → Plot layers: configures fields