# ndf-poli-usp/spyro architecture

> Architecture diagram of the GitHub repository ndf-poli-usp/spyro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ndf-poli-usp/spyro
- Repository: https://github.com/ndf-poli-usp/spyro

## Overview

Spyro is a Firedrake-based seismic wave modeling and inversion library. The main workflow configures a model and mesh, injects seismic sources, propagates acoustic waves, samples receiver data, and—when running FWI—compares synthetic and observed records to optimize the velocity model. The map also retains documented mesh, PML, parallelism, and adjoint capabilities. Relationships are limited to README statements and source-index references; unsampled implementation details are not assumed.

Main entry points: [`spyro/solvers/wave.py`](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/wave.py) (Wave solver API), [`spyro/solvers/inversion.py`](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/inversion.py) (FWI driver), [`spyro/solvers/acoustic_wave.py`](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/acoustic_wave.py) (Acoustic propagation), [`spyro/io/model_parameters.py`](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/model_parameters.py) (Model configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model setup"]
  node_config["Model configuration"]
  node_mesh["Mesh generation"]
  node_space["Finite element spaces<br/>[space.py]"]
  node_materials["Material fields"]
  node_pml["PML boundaries<br/>[pml_nsnc.py]"]
  node_habc["Hybrid absorbing layers<br/>[abc_layer.py]"]
end

subgraph group_propagation["Wave simulation"]
  node_wave["Wave solver API<br/>[wave.py]"]
  node_acoustic["Acoustic propagation<br/>[acoustic_wave.py]"]
  node_integrator["Time integration"]
  node_sources["Seismic sources<br/>[Sources.py]"]
  node_receivers["Receiver sampling<br/>[Receivers.py]"]
  node_elastic["Elastic wave modeling<br/>[isotropic_wave.py]"]
  node_eikonal["Eikonal solver<br/>[eikonal_eq.py]"]
end

subgraph group_inversion["Inversion and analysis"]
  node_fwi["FWI driver<br/>[inversion.py]"]
  node_functionals["Misfit functionals<br/>[functionals.py]"]
  node_adjoint["Adjoint propagation"]
end

subgraph group_runtime["Runtime support"]
  node_io["Shot and model I/O<br/>[basicio.py]"]
  node_parallel["Ensemble parallelism<br/>[spyro_mpi.py]"]
  node_plots["Wave visualization<br/>[general_plots.py]"]
end

node_user(("Researcher"))

node_user -->|"configures"| node_config
node_config -->|"sets parameters"| node_mesh
node_wave -->|"uses spaces"| node_space
node_wave -->|"loads fields"| node_materials
node_wave -->|"uses sources"| node_sources
node_wave -->|"samples receivers"| node_receivers
node_wave -->|"propagates with"| node_integrator
node_acoustic -->|"extends API"| node_wave
node_acoustic -->|"uses ensembles"| node_parallel
node_sources -->|"uses projector"| node_receivers
node_fwi -->|"constructs solver"| node_acoustic
node_fwi -->|"sets mesh"| node_wave
node_fwi -->|"evaluates objective"| node_functionals
node_fwi -.->|"computes gradient"| node_adjoint
node_fwi -->|"visualizes results"| node_plots
node_wave -.->|"supports boundaries"| node_pml
node_wave -.->|"supports boundaries"| node_habc
node_mesh -->|"builds layer mesh"| node_habc
node_io -->|"uses ensemble I/O"| node_parallel
node_wave -->|"uses I/O helpers"| node_io
node_user -.->|"models elastic waves"| node_elastic
node_user -.->|"solves travel times"| node_eikonal

click node_config "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/model_parameters.py"
click node_mesh "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/meshing/meshing_functions.py"
click node_space "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/domains/space.py"
click node_materials "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/material_properties_io.py"
click node_pml "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/pml/pml_nsnc.py"
click node_habc "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/abc/abc_layer.py"
click node_wave "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/wave.py"
click node_acoustic "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/acoustic_wave.py"
click node_integrator "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/time_integration_central_difference.py"
click node_sources "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/sources/Sources.py"
click node_receivers "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/receivers/Receivers.py"
click node_io "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/basicio.py"
click node_parallel "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/mpi/spyro_mpi.py"
click node_fwi "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/inversion.py"
click node_functionals "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/functionals.py"
click node_adjoint "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/backward_time_integration.py"
click node_plots "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/plots/general_plots.py"
click node_elastic "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/elastic_wave/isotropic_wave.py"
click node_eikonal "https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/eikonal/eikonal_eq.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_mesh,node_space,node_materials,node_pml,node_habc toneBlue
class node_wave,node_acoustic,node_integrator,node_sources,node_receivers,node_elastic,node_eikonal toneAmber
class node_fwi,node_functionals,node_adjoint toneMint
class node_io,node_parallel,node_plots toneRose
class node_user toneIndigo
```

## Components

### Model setup

- [Model configuration](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/model_parameters.py): `spyro/io/model_parameters.py`
- [Mesh generation](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/meshing/meshing_functions.py): `spyro/meshing/meshing_functions.py`
- [Finite element spaces](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/domains/space.py): `spyro/domains/space.py`
- [Material fields](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/material_properties_io.py): `spyro/io/material_properties_io.py`
- [PML boundaries](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/pml/pml_nsnc.py): `spyro/pml/pml_nsnc.py`
- [Hybrid absorbing layers](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/abc/abc_layer.py): `spyro/abc/abc_layer.py`

### Wave simulation

- [Wave solver API](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/wave.py): `spyro/solvers/wave.py`
- [Acoustic propagation](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/acoustic_wave.py): `spyro/solvers/acoustic_wave.py`
- [Time integration](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/time_integration_central_difference.py): `spyro/solvers/time_integration_central_difference.py`
- [Seismic sources](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/sources/Sources.py): `spyro/sources/Sources.py`
- [Receiver sampling](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/receivers/Receivers.py): `spyro/receivers/Receivers.py`
- [Elastic wave modeling](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/elastic_wave/isotropic_wave.py): `spyro/solvers/elastic_wave/isotropic_wave.py`
- [Eikonal solver](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/eikonal/eikonal_eq.py): `spyro/solvers/eikonal/eikonal_eq.py`

### Inversion and analysis

- [FWI driver](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/inversion.py): `spyro/solvers/inversion.py`
- [Misfit functionals](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/functionals.py): `spyro/solvers/functionals.py`
- [Adjoint propagation](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/solvers/backward_time_integration.py): `spyro/solvers/backward_time_integration.py`

### Runtime support

- [Shot and model I/O](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/io/basicio.py): `spyro/io/basicio.py`
- [Ensemble parallelism](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/mpi/spyro_mpi.py): `spyro/mpi/spyro_mpi.py`
- [Wave visualization](https://github.com/ndf-poli-usp/spyro/blob/main/spyro/plots/general_plots.py): `spyro/plots/general_plots.py`

### Other components

- **Researcher**

## Connections

- Researcher → Model configuration: configures
- Model configuration → Mesh generation: sets parameters (evidence: `spyro/io/model_parameters.py`)
- Wave solver API → Finite element spaces: uses spaces (evidence: `spyro/solvers/wave.py`)
- Wave solver API → Material fields: loads fields (evidence: `spyro/solvers/wave.py`)
- Wave solver API → Seismic sources: uses sources (evidence: `spyro/solvers/wave.py`)
- Wave solver API → Receiver sampling: samples receivers (evidence: `spyro/solvers/wave.py`)
- Wave solver API → Time integration: propagates with (evidence: `spyro/solvers/wave.py`)
- Acoustic propagation → Wave solver API: extends API (evidence: `spyro/solvers/acoustic_wave.py`)
- Acoustic propagation → Ensemble parallelism: uses ensembles (evidence: `spyro/solvers/acoustic_wave.py`)
- Seismic sources → Receiver sampling: uses projector (evidence: `spyro/sources/Sources.py`)
- FWI driver → Acoustic propagation: constructs solver (evidence: `spyro/solvers/inversion.py`)
- FWI driver → Wave solver API: sets mesh (evidence: `spyro/solvers/inversion.py`)
- FWI driver → Misfit functionals: evaluates objective (evidence: `spyro/solvers/inversion.py`)
- FWI driver → Adjoint propagation: computes gradient
- FWI driver → Wave visualization: visualizes results (evidence: `spyro/solvers/inversion.py`)
- Wave solver API → PML boundaries: supports boundaries (evidence: `spyro/solvers/wave.py`)
- Wave solver API → Hybrid absorbing layers: supports boundaries
- Mesh generation → Hybrid absorbing layers: builds layer mesh
- Shot and model I/O → Ensemble parallelism: uses ensemble I/O (evidence: `spyro/io/basicio.py`)
- Wave solver API → Shot and model I/O: uses I/O helpers (evidence: `spyro/solvers/wave.py`)
- Researcher → Elastic wave modeling: models elastic waves
- Researcher → Eikonal solver: solves travel times
