# onera/maia architecture

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

- Interactive diagram: https://gitdiagram.com/onera/maia
- Repository: https://github.com/onera/maia

## Overview

Maia is a Python/C++ library for parallel algorithms and manipulations on CGNS meshes. Its core workflow is to represent mesh data as CGNS trees, partition or distribute those trees, apply mesh algorithms, and exchange or recover data across representations. The README identifies ParaDiGM as the parallel backend. The tree also shows substantial I/O, PyTree utilities, and mesh-checking capabilities. Several relationships below are documented at product level; sampled source gives more specific evidence for point search and transfer behavior, while unsampled internals are not assumed.

Main entry points: [`maia/__init__.py`](https://github.com/onera/maia/blob/dev/maia/__init__.py) (Maia API), [`maia/transfer/protocols.py`](https://github.com/onera/maia/blob/dev/maia/transfer/protocols.py) (Exchange protocols), [`maia/algo/geosearch.py`](https://github.com/onera/maia/blob/dev/maia/algo/geosearch.py) (Point localization), [`maia/transfer/part_to_dist/index_exchange.py`](https://github.com/onera/maia/blob/dev/maia/transfer/part_to_dist/index_exchange.py) (Partition to block)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tree["CGNS Trees"]
  node_pytree["PyTree model<br/>[access.py]"]
  node_tree_search["Tree search<br/>[search.py]"]
  node_tree_inspect["Tree inspection<br/>[inspect.py]"]
  node_tree_walk["Tree traversal<br/>[node_walker.py]"]
  node_tree_schema["CGNS definitions<br/>[elements_utils.py]"]
end

subgraph group_partition["Mesh Distribution"]
  node_factory["Mesh factories<br/>[dcube_generator.py]"]
  node_partitioning["Mesh partitioning<br/>[partitioning.py]"]
  node_orient["Boundary orientation"]
  node_recover["Tree recovery<br/>[dist_from_part.py]"]
end

subgraph group_compute["Mesh Algorithms"]
  node_geometry["Geometry tools<br/>[measures.py]"]
  node_pointcloud["Point cloud tools"]
  node_isosurface["Isosurface extraction<br/>[isosurf.py]"]
  node_geosearch["Point localization<br/>[geosearch.py]"]
end

subgraph group_exchange["Parallel Transfer"]
  node_transfer_api["Exchange protocols<br/>[protocols.py]"]
  node_part_dist["Partition to block<br/>[index_exchange.py]"]
  node_dist_part["Block to partition<br/>[data_exchange.py]"]
  node_transfer_utils["Transfer utilities<br/>[utils.py]"]
end

subgraph group_support["I/O and Validation"]
  node_io["CGNS mesh I/O"]
  node_checker["CGNS checking"]
end

node_user(("Library user"))
node_maia["Maia API<br/>[__init__.py]"]
node_paradigm["ParaDiGM"]
node_mpi["MPI runtime"]

node_user -->|"uses"| node_maia
node_maia -->|"exposes"| node_pytree
node_maia -->|"exposes"| node_factory
node_maia -->|"exposes"| node_io
node_maia -->|"exposes"| node_transfer_api
node_geosearch -->|"reads trees"| node_pytree
node_geosearch -.->|"uses communicator"| node_mpi
node_part_dist -->|"exchanges indices"| node_transfer_api
node_part_dist -->|"uses numbering"| node_transfer_utils
node_dist_part -->|"uses protocols"| node_transfer_api
node_factory -.->|"uses backend"| node_paradigm
node_maia -->|"uses backend"| node_paradigm

click node_maia "https://github.com/onera/maia/blob/dev/maia/__init__.py"
click node_pytree "https://github.com/onera/maia/blob/dev/maia/pytree/node/access.py"
click node_tree_search "https://github.com/onera/maia/blob/dev/maia/pytree/maia/search.py"
click node_tree_inspect "https://github.com/onera/maia/blob/dev/maia/pytree/maia/inspect.py"
click node_tree_walk "https://github.com/onera/maia/blob/dev/maia/pytree/walk/node_walker.py"
click node_tree_schema "https://github.com/onera/maia/blob/dev/maia/pytree/sids/elements_utils.py"
click node_factory "https://github.com/onera/maia/blob/dev/maia/factory/dcube_generator.py"
click node_partitioning "https://github.com/onera/maia/blob/dev/maia/factory/partitioning/partitioning.py"
click node_orient "https://github.com/onera/maia/blob/dev/maia/factory/partitioning/part_bound_orient.py"
click node_recover "https://github.com/onera/maia/blob/dev/maia/factory/dist_from_part.py"
click node_geometry "https://github.com/onera/maia/blob/dev/maia/algo/part/geometry/measures.py"
click node_pointcloud "https://github.com/onera/maia/blob/dev/maia/algo/part/point_cloud_utils.py"
click node_isosurface "https://github.com/onera/maia/blob/dev/maia/algo/part/isosurf.py"
click node_geosearch "https://github.com/onera/maia/blob/dev/maia/algo/geosearch.py"
click node_transfer_api "https://github.com/onera/maia/blob/dev/maia/transfer/protocols.py"
click node_part_dist "https://github.com/onera/maia/blob/dev/maia/transfer/part_to_dist/index_exchange.py"
click node_dist_part "https://github.com/onera/maia/blob/dev/maia/transfer/dist_to_part/data_exchange.py"
click node_transfer_utils "https://github.com/onera/maia/blob/dev/maia/transfer/utils.py"
click node_io "https://github.com/onera/maia/tree/dev/maia/io"
click node_checker "https://github.com/onera/maia/tree/dev/bin/_cgns_check"

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_pytree,node_tree_search,node_tree_inspect,node_tree_walk,node_tree_schema,node_user toneBlue
class node_factory,node_partitioning,node_orient,node_recover toneAmber
class node_geometry,node_pointcloud,node_isosurface,node_geosearch,node_maia toneMint
class node_transfer_api,node_part_dist,node_dist_part,node_transfer_utils toneRose
class node_io,node_checker,node_paradigm,node_mpi toneIndigo
```

## Components

### CGNS Trees

- [PyTree model](https://github.com/onera/maia/blob/dev/maia/pytree/node/access.py): `maia/pytree/node/access.py`
- [Tree search](https://github.com/onera/maia/blob/dev/maia/pytree/maia/search.py): `maia/pytree/maia/search.py`
- [Tree inspection](https://github.com/onera/maia/blob/dev/maia/pytree/maia/inspect.py): `maia/pytree/maia/inspect.py`
- [Tree traversal](https://github.com/onera/maia/blob/dev/maia/pytree/walk/node_walker.py): `maia/pytree/walk/node_walker.py`
- [CGNS definitions](https://github.com/onera/maia/blob/dev/maia/pytree/sids/elements_utils.py): `maia/pytree/sids/elements_utils.py`

### Mesh Distribution

- [Mesh factories](https://github.com/onera/maia/blob/dev/maia/factory/dcube_generator.py): `maia/factory/dcube_generator.py`
- [Mesh partitioning](https://github.com/onera/maia/blob/dev/maia/factory/partitioning/partitioning.py): `maia/factory/partitioning/partitioning.py`
- [Boundary orientation](https://github.com/onera/maia/blob/dev/maia/factory/partitioning/part_bound_orient.py): `maia/factory/partitioning/part_bound_orient.py`
- [Tree recovery](https://github.com/onera/maia/blob/dev/maia/factory/dist_from_part.py): `maia/factory/dist_from_part.py`

### Mesh Algorithms

- [Geometry tools](https://github.com/onera/maia/blob/dev/maia/algo/part/geometry/measures.py): `maia/algo/part/geometry/measures.py`
- [Point cloud tools](https://github.com/onera/maia/blob/dev/maia/algo/part/point_cloud_utils.py): `maia/algo/part/point_cloud_utils.py`
- [Isosurface extraction](https://github.com/onera/maia/blob/dev/maia/algo/part/isosurf.py): `maia/algo/part/isosurf.py`
- [Point localization](https://github.com/onera/maia/blob/dev/maia/algo/geosearch.py): `maia/algo/geosearch.py`

### Parallel Transfer

- [Exchange protocols](https://github.com/onera/maia/blob/dev/maia/transfer/protocols.py): `maia/transfer/protocols.py`
- [Partition to block](https://github.com/onera/maia/blob/dev/maia/transfer/part_to_dist/index_exchange.py): `maia/transfer/part_to_dist/index_exchange.py`
- [Block to partition](https://github.com/onera/maia/blob/dev/maia/transfer/dist_to_part/data_exchange.py): `maia/transfer/dist_to_part/data_exchange.py`
- [Transfer utilities](https://github.com/onera/maia/blob/dev/maia/transfer/utils.py): `maia/transfer/utils.py`

### I/O and Validation

- [CGNS mesh I/O](https://github.com/onera/maia/tree/dev/maia/io): `maia/io`
- [CGNS checking](https://github.com/onera/maia/tree/dev/bin/_cgns_check): `bin/_cgns_check`

### Other components

- **Library user**
- [Maia API](https://github.com/onera/maia/blob/dev/maia/__init__.py): `maia/__init__.py`
- **ParaDiGM**
- **MPI runtime**

## Connections

- Library user → Maia API: uses (evidence: `README.md`)
- Maia API → PyTree model: exposes (evidence: `maia/__init__.py`)
- Maia API → Mesh factories: exposes (evidence: `maia/__init__.py`)
- Maia API → CGNS mesh I/O: exposes (evidence: `maia/__init__.py`)
- Maia API → Exchange protocols: exposes (evidence: `maia/__init__.py`)
- Point localization → PyTree model: reads trees (evidence: `maia/algo/geosearch.py`)
- Point localization → MPI runtime: uses communicator
- Partition to block → Exchange protocols: exchanges indices (evidence: `maia/transfer/part_to_dist/index_exchange.py`)
- Partition to block → Transfer utilities: uses numbering (evidence: `maia/transfer/part_to_dist/index_exchange.py`)
- Block to partition → Exchange protocols: uses protocols (evidence: `maia/transfer/dist_to_part/data_exchange.py`)
- Mesh factories → ParaDiGM: uses backend
- Maia API → ParaDiGM: uses backend (evidence: `README.md`)
