# mgenet/dolfin_warp architecture

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

- Interactive diagram: https://gitdiagram.com/mgenet/dolfin_warp
- Repository: https://github.com/mgenet/dolfin_warp

## Overview

dolfin_warp is a FEniCS- and VTK-based finite-element image-registration and motion-tracking library. Its principal workflow takes an image series and mesh, configures a warping problem with image and mechanical regularization energies, solves for deformation across frames, and supports derived displacement/strain analysis and visualization. Separate utilities generate synthetic images and compute image or mesh outputs. The README documents broader capabilities than the sampled source; links below reflect explicit wiring where available, and unsampled subsystem connections are kept conservative.

Main entry points: [`dolfin_warp/warp.py`](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/warp.py) (Warp driver), [`dolfin_warp/Problem_Warping.py`](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_Warping.py) (Warping problem), [`dolfin_warp/NonlinearSolver.py`](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver.py) (Nonlinear solvers), [`dolfin_warp/EnergyMixin_Image.py`](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Image.py) (Image energies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Warp workflow"]
  node_warp["Warp driver<br/>[warp.py]"]
  node_solver["Nonlinear solvers<br/>[NonlinearSolver.py]"]
  node_newton["Newton solver"]
  node_scipy["SciPy solver"]
end

subgraph group_model["Problem and energies"]
  node_problem["Warping problem<br/>[Problem_Warping.py]"]
  node_full["Full kinematics"]
  node_reduced["Reduced kinematics"]
  node_energy["Energy base<br/>[Energy.py]"]
  node_continuous["Continuous energies"]
  node_discrete["Discrete energies"]
  node_imageenergy["Image energies"]
end

subgraph group_imaging["Images and meshes"]
  node_series["Image series"]
  node_meshseries["Mesh series"]
  node_iterator["Frame iterator<br/>[ImageIterator.py]"]
  node_expr["Image expressions"]
  node_generatedexpr["Generated expressions"]
end

subgraph group_analysis["Generation and analysis"]
  node_gen["Image generator<br/>[generate_images.py]"]
  node_imagegen["Image models"]
  node_warpout["Warped outputs"]
  node_meshout["Warped mesh"]
  node_strains["Strain computation<br/>[compute_strains.py]"]
  node_plots["Strain plots<br/>[plot_strains.py]"]
end

node_user(("Researcher"))
node_external["FEniCS and VTK"]

node_user -->|"configures"| node_warp
node_warp -->|"creates"| node_problem
node_warp -->|"loads frames"| node_series
node_warp -->|"loads meshes"| node_meshseries
node_warp -->|"selects"| node_full
node_warp -->|"selects"| node_reduced
node_warp -->|"adds image term"| node_imageenergy
node_warp -->|"adds regularization"| node_continuous
node_warp -->|"adds regularization"| node_discrete
node_problem -->|"evaluates"| node_energy
node_problem -->|"solved by"| node_solver
node_solver -->|"dispatches"| node_newton
node_solver -->|"dispatches"| node_scipy
node_series -->|"iterates frames"| node_iterator
node_series -->|"supplies images"| node_expr
node_imageenergy -->|"samples images"| node_expr
node_imageenergy -->|"samples generated images"| node_generatedexpr
node_expr -->|"uses"| node_external
node_generatedexpr -->|"uses"| node_external
node_problem -->|"uses finite elements"| node_external
node_user -->|"specifies synthetic data"| node_gen
node_gen -->|"constructs image model"| node_imagegen
node_user -->|"requests derived outputs"| node_warpout
node_user -->|"requests derived outputs"| node_meshout
node_user -->|"requests analysis"| node_strains
node_meshseries -->|"provides mesh frames"| node_strains
node_strains -->|"feeds plots"| node_plots
node_problem -.->|"provides deformation"| node_warpout
node_problem -.->|"provides deformation"| node_meshout

click node_warp "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/warp.py"
click node_problem "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_Warping.py"
click node_full "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_FullKinematicsWarping.py"
click node_reduced "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_ReducedKinematicsWarping.py"
click node_energy "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Energy.py"
click node_continuous "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Continuous.py"
click node_discrete "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Discrete.py"
click node_imageenergy "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Image.py"
click node_solver "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver.py"
click node_newton "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver_Newton.py"
click node_scipy "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver_Scipy.py"
click node_series "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/FileSeries_Images.py"
click node_meshseries "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/FileSeries_Meshes.py"
click node_iterator "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/ImageIterator.py"
click node_expr "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/expressions_images_cpp.py"
click node_generatedexpr "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/expressions_generated_images_cont_cpp.py"
click node_gen "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/generate_images.py"
click node_imagegen "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/generate_images_Image.py"
click node_warpout "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_warped_images.py"
click node_meshout "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_warped_mesh.py"
click node_strains "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_strains.py"
click node_plots "https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/plot_strains.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_warp,node_solver,node_newton,node_scipy toneBlue
class node_problem,node_full,node_reduced,node_energy,node_continuous,node_discrete,node_imageenergy toneAmber
class node_series,node_meshseries,node_iterator,node_expr,node_generatedexpr toneMint
class node_gen,node_imagegen,node_warpout,node_meshout,node_strains,node_plots toneRose
class node_user,node_external toneIndigo
```

## Components

### Warp workflow

- [Warp driver](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/warp.py): `dolfin_warp/warp.py`
- [Nonlinear solvers](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver.py): `dolfin_warp/NonlinearSolver.py`
- [Newton solver](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver_Newton.py): `dolfin_warp/NonlinearSolver_Newton.py`
- [SciPy solver](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/NonlinearSolver_Scipy.py): `dolfin_warp/NonlinearSolver_Scipy.py`

### Problem and energies

- [Warping problem](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_Warping.py): `dolfin_warp/Problem_Warping.py`
- [Full kinematics](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_FullKinematicsWarping.py): `dolfin_warp/Problem_FullKinematicsWarping.py`
- [Reduced kinematics](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Problem_ReducedKinematicsWarping.py): `dolfin_warp/Problem_ReducedKinematicsWarping.py`
- [Energy base](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/Energy.py): `dolfin_warp/Energy.py`
- [Continuous energies](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Continuous.py): `dolfin_warp/EnergyMixin_Continuous.py`
- [Discrete energies](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Discrete.py): `dolfin_warp/EnergyMixin_Discrete.py`
- [Image energies](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/EnergyMixin_Image.py): `dolfin_warp/EnergyMixin_Image.py`

### Images and meshes

- [Image series](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/FileSeries_Images.py): `dolfin_warp/FileSeries_Images.py`
- [Mesh series](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/FileSeries_Meshes.py): `dolfin_warp/FileSeries_Meshes.py`
- [Frame iterator](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/ImageIterator.py): `dolfin_warp/ImageIterator.py`
- [Image expressions](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/expressions_images_cpp.py): `dolfin_warp/expressions_images_cpp.py`
- [Generated expressions](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/expressions_generated_images_cont_cpp.py): `dolfin_warp/expressions_generated_images_cont_cpp.py`

### Generation and analysis

- [Image generator](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/generate_images.py): `dolfin_warp/generate_images.py`
- [Image models](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/generate_images_Image.py): `dolfin_warp/generate_images_Image.py`
- [Warped outputs](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_warped_images.py): `dolfin_warp/compute_warped_images.py`
- [Warped mesh](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_warped_mesh.py): `dolfin_warp/compute_warped_mesh.py`
- [Strain computation](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/compute_strains.py): `dolfin_warp/compute_strains.py`
- [Strain plots](https://github.com/mgenet/dolfin_warp/blob/master/dolfin_warp/plot_strains.py): `dolfin_warp/plot_strains.py`

### Other components

- **Researcher**
- **FEniCS and VTK**

## Connections

- Researcher → Warp driver: configures
- Warp driver → Warping problem: creates
- Warp driver → Image series: loads frames
- Warp driver → Mesh series: loads meshes
- Warp driver → Full kinematics: selects
- Warp driver → Reduced kinematics: selects
- Warp driver → Image energies: adds image term
- Warp driver → Continuous energies: adds regularization
- Warp driver → Discrete energies: adds regularization
- Warping problem → Energy base: evaluates
- Warping problem → Nonlinear solvers: solved by
- Nonlinear solvers → Newton solver: dispatches
- Nonlinear solvers → SciPy solver: dispatches
- Image series → Frame iterator: iterates frames
- Image series → Image expressions: supplies images
- Image energies → Image expressions: samples images
- Image energies → Generated expressions: samples generated images
- Image expressions → FEniCS and VTK: uses
- Generated expressions → FEniCS and VTK: uses
- Warping problem → FEniCS and VTK: uses finite elements
- Researcher → Image generator: specifies synthetic data
- Image generator → Image models: constructs image model
- Researcher → Warped outputs: requests derived outputs
- Researcher → Warped mesh: requests derived outputs
- Researcher → Strain computation: requests analysis
- Mesh series → Strain computation: provides mesh frames
- Strain computation → Strain plots: feeds plots
- Warping problem → Warped outputs: provides deformation
- Warping problem → Warped mesh: provides deformation