# multisimolab/hypershape.jl architecture

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

- Interactive diagram: https://gitdiagram.com/multisimolab/hypershape.jl
- Repository: https://github.com/multisimolab/hypershape.jl

## Overview

HyperShape is a Julia library for shape and topology optimisation of nonlinear multiphysics models. The documented workflow maps optimiser variables to design and physical fields, solves forward and adjoint states using user-configured HyperFEM models, evaluates objectives and sensitivities, then lets an optimisation method update the design. Its major capabilities include SIMP, reaction–diffusion and level-set methods, finite-element-independent optimisers, auxiliary linear solves and user-defined iteration output. Source excerpts were not provided, so relationships below rely on the README’s planned architecture and documented roles.

Main entry points: [`src/Methods/Loop.jl`](https://github.com/multisimolab/hypershape.jl/blob/main/src/Methods/Loop.jl) (Optimisation loop), [`src/Functionals/Functionals.jl`](https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl) (Functionals), [`src/Optimizers/Interface.jl`](https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/Interface.jl) (Optimizer interface), [`src/Variables/OptVariables.jl`](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/OptVariables.jl) (OptVariables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_design["Design variables"]
  node_optimizer_input["OptVariables<br/>[OptVariables.jl]"]
  node_design_fields["DesignFields<br/>[DesignFields.jl]"]
  node_physical_fields["PhysicalFields<br/>[PhysicalFields.jl]"]
  node_assembly["Variable assembly<br/>[Assembly.jl]"]
  node_maps["Variable maps<br/>[Maps.jl]"]
end

subgraph group_solves["State solves"]
  node_state["StateOperator<br/>[StateOperator.jl]"]
  node_adjoint["AdjointOperator<br/>[StateOperator.jl]"]
end

subgraph group_optimisation["Optimisation"]
  node_functionals["Functionals<br/>[Functionals.jl]"]
  node_volume["Volume constraint<br/>[Functionals.jl]"]
  node_sensitivities["Sensitivity evaluation<br/>[Functionals.jl]"]
  node_methods["Optimisation loop<br/>[Loop.jl]"]
  node_method_families["SIMP, RD, LevelSet"]
  node_oc["Optimality criteria<br/>[OC.jl]"]
  node_simpl["SiMPL<br/>[SiMPL.jl]"]
  node_optimizer_interface["Optimizer interface<br/>[Interface.jl]"]
end

subgraph group_support["Supporting operations"]
  node_linear["LinearOperator<br/>[Operators.jl]"]
  node_postprocess["Iteration output<br/>[Output.jl]"]
end

node_hyperfem["HyperFEM models"]
node_user(("User configuration"))

node_optimizer_input -->|"maps to"| node_design_fields
node_design_fields -->|"maps to"| node_physical_fields
node_physical_fields -->|"configures fields"| node_hyperfem
node_hyperfem -->|"provides models"| node_state
node_state -->|"supports adjoint"| node_adjoint
node_adjoint -->|"provides states"| node_functionals
node_functionals -->|"includes constraint"| node_volume
node_functionals -->|"computes derivatives"| node_sensitivities
node_sensitivities -->|"supplies sensitivities"| node_methods
node_methods -->|"selects step"| node_method_families
node_methods -->|"updates variables"| node_optimizer_input
node_optimizer_interface -->|"supports"| node_oc
node_optimizer_interface -->|"supports"| node_simpl
node_methods -->|"emits iteration output"| node_postprocess
node_user -->|"configures models"| node_hyperfem
node_user -->|"writes output"| node_postprocess
node_user -->|"configures solves"| node_linear

click node_optimizer_input "https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/OptVariables.jl"
click node_design_fields "https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/DesignFields.jl"
click node_physical_fields "https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/PhysicalFields.jl"
click node_assembly "https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/Assembly.jl"
click node_maps "https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/Maps.jl"
click node_state "https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/StateOperator.jl"
click node_adjoint "https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/StateOperator.jl"
click node_functionals "https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl"
click node_volume "https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl"
click node_sensitivities "https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl"
click node_methods "https://github.com/multisimolab/hypershape.jl/blob/main/src/Methods/Loop.jl"
click node_method_families "https://github.com/multisimolab/hypershape.jl/tree/main/src/Methods"
click node_oc "https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/OC.jl"
click node_simpl "https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/SiMPL.jl"
click node_optimizer_interface "https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/Interface.jl"
click node_linear "https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/Operators.jl"
click node_postprocess "https://github.com/multisimolab/hypershape.jl/blob/main/src/Methods/Output.jl"

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_optimizer_input,node_design_fields,node_physical_fields,node_assembly,node_maps,node_user toneBlue
class node_state,node_adjoint toneAmber
class node_functionals,node_volume,node_sensitivities,node_methods,node_method_families,node_oc,node_simpl,node_optimizer_interface toneMint
class node_linear,node_postprocess toneRose
class node_hyperfem toneIndigo
```

## Components

### Design variables

- [OptVariables](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/OptVariables.jl): `src/Variables/OptVariables.jl`
- [DesignFields](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/DesignFields.jl): `src/Variables/DesignFields.jl`
- [PhysicalFields](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/PhysicalFields.jl): `src/Variables/PhysicalFields.jl`
- [Variable assembly](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/Assembly.jl): `src/Variables/Assembly.jl`
- [Variable maps](https://github.com/multisimolab/hypershape.jl/blob/main/src/Variables/Maps.jl): `src/Variables/Maps.jl`

### State solves

- [StateOperator](https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/StateOperator.jl): `src/Operators/StateOperator.jl`
- [AdjointOperator](https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/StateOperator.jl): `src/Operators/StateOperator.jl`

### Optimisation

- [Functionals](https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl): `src/Functionals/Functionals.jl`
- [Volume constraint](https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl): `src/Functionals/Functionals.jl`
- [Sensitivity evaluation](https://github.com/multisimolab/hypershape.jl/blob/main/src/Functionals/Functionals.jl): `src/Functionals/Functionals.jl`
- [Optimisation loop](https://github.com/multisimolab/hypershape.jl/blob/main/src/Methods/Loop.jl): `src/Methods/Loop.jl`
- [SIMP, RD, LevelSet](https://github.com/multisimolab/hypershape.jl/tree/main/src/Methods): `src/Methods`
- [Optimality criteria](https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/OC.jl): `src/Optimizers/OC.jl`
- [SiMPL](https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/SiMPL.jl): `src/Optimizers/SiMPL.jl`
- [Optimizer interface](https://github.com/multisimolab/hypershape.jl/blob/main/src/Optimizers/Interface.jl): `src/Optimizers/Interface.jl`

### Supporting operations

- [LinearOperator](https://github.com/multisimolab/hypershape.jl/blob/main/src/Operators/Operators.jl): `src/Operators/Operators.jl`
- [Iteration output](https://github.com/multisimolab/hypershape.jl/blob/main/src/Methods/Output.jl): `src/Methods/Output.jl`

### Other components

- **HyperFEM models**
- **User configuration**

## Connections

- OptVariables → DesignFields: maps to (evidence: `README.md`)
- DesignFields → PhysicalFields: maps to (evidence: `README.md`)
- PhysicalFields → HyperFEM models: configures fields (evidence: `README.md`)
- HyperFEM models → StateOperator: provides models (evidence: `README.md`)
- StateOperator → AdjointOperator: supports adjoint (evidence: `README.md`)
- AdjointOperator → Functionals: provides states (evidence: `README.md`)
- Functionals → Volume constraint: includes constraint (evidence: `README.md`)
- Functionals → Sensitivity evaluation: computes derivatives (evidence: `README.md`)
- Sensitivity evaluation → Optimisation loop: supplies sensitivities (evidence: `README.md`)
- Optimisation loop → SIMP, RD, LevelSet: selects step (evidence: `README.md`)
- Optimisation loop → OptVariables: updates variables (evidence: `README.md`)
- Optimizer interface → Optimality criteria: supports (evidence: `README.md`)
- Optimizer interface → SiMPL: supports (evidence: `README.md`)
- Optimisation loop → Iteration output: emits iteration output (evidence: `README.md`)
- User configuration → HyperFEM models: configures models (evidence: `README.md`)
- User configuration → Iteration output: writes output (evidence: `README.md`)
- User configuration → LinearOperator: configures solves (evidence: `README.md`)
