# marinamaia2021/fe2_fenicsx architecture

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

- Interactive diagram: https://gitdiagram.com/marinamaia2021/fe2_fenicsx
- Repository: https://github.com/marinamaia2021/fe2_fenicsx

## Overview

This repository implements research code for two-dimensional multiscale finite-element (FE²) simulations of nonlinear composite materials. The principal workflow is to define a macroscopic domain and loading, solve its nonlinear equilibrium problem, and use quadrature-point updates to obtain response from periodic representative volume elements (RVEs). RVE variants cover J2 plasticity and fiber–matrix composites; JAX modules provide constitutive updates. The excerpts show the macro solver, mesh and RVE setup, and plotting, but not the full quadrature-to-RVE update path, so uncertain runtime links are omitted.

Main entry points: [`fe2_refac.py`](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/fe2_refac.py) (FE² driver), [`jax_j2.py`](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/jax_j2.py) (J2 material model), [`customnewtonproblem.py`](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/customnewtonproblem.py) (Newton solver), [`rve_j2_linear_clean.py`](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_j2_linear_clean.py) (J2 RVE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_macro["Macro simulation"]
  node_macro_domain["Macro domain<br/>[macromodel.py]"]
  node_macro_solver["FE² driver<br/>[fe2_refac.py]"]
  node_newton["Newton solver"]
  node_load_utils["Loading and solver utilities<br/>[auxFunctions.py]"]
end

subgraph group_coupling["FE² coupling"]
  node_quadrature["Quadrature mapping<br/>[quadrature.py]"]
  node_plotting["Plotting domain<br/>[quadrature.py]"]
end

subgraph group_rves["RVE models"]
  node_rve_clean["J2 RVE"]
  node_rve_legacy["J2 RVE variant<br/>[rve_j2_linear.py]"]
  node_rve_external["External JAX RVE<br/>[rve_ext_clean.py]"]
  node_rve_refactored["Refactored RVE"]
  node_rve_composite["Fiber–matrix RVE"]
end

subgraph group_materials["Constitutive models"]
  node_j2_model["Plane-stress J2<br/>[j2_jax.py]"]
  node_jax_model["J2 material model<br/>[jax_j2.py]"]
  node_jax_utils["JAX utilities<br/>[utils_jax.py]"]
  node_prnn["PRNN model<br/>[prnn_jax.py]"]
end

node_researcher(("Simulation user"))

node_researcher -->|"runs simulation"| node_macro_solver
node_macro_solver -->|"creates domain"| node_macro_domain
node_macro_solver -->|"uses solver"| node_newton
node_newton -->|"configures solver"| node_load_utils
node_macro_solver -->|"uses mapping"| node_quadrature
node_macro_solver -->|"loads RVE class"| node_rve_clean
node_macro_solver -->|"loads RVE class"| node_rve_composite
node_macro_solver -->|"loads RVE class"| node_rve_refactored
node_macro_solver -->|"updates plots"| node_plotting
node_rve_clean -->|"uses material model"| node_j2_model
node_rve_legacy -->|"uses material model"| node_j2_model
node_rve_external -->|"uses material model"| node_jax_model
node_rve_refactored -->|"uses material model"| node_jax_model
node_rve_composite -->|"uses material model"| node_jax_model
node_prnn -->|"imports model"| node_jax_model

click node_macro_domain "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/macromodel.py"
click node_macro_solver "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/fe2_refac.py"
click node_newton "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/customnewtonproblem.py"
click node_load_utils "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/auxFunctions.py"
click node_quadrature "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/quadrature.py"
click node_plotting "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/quadrature.py"
click node_rve_clean "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_j2_linear_clean.py"
click node_rve_legacy "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_j2_linear.py"
click node_rve_external "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_ext_clean.py"
click node_rve_refactored "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_ext_clean_refac.py"
click node_rve_composite "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_fiber_matrix.py"
click node_j2_model "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/j2_jax.py"
click node_jax_model "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/jax_j2.py"
click node_jax_utils "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/utils_jax.py"
click node_prnn "https://github.com/marinamaia2021/fe2_fenicsx/blob/main/prnn_jax.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_macro_domain,node_macro_solver,node_newton,node_load_utils,node_researcher toneBlue
class node_quadrature,node_plotting toneAmber
class node_rve_clean,node_rve_legacy,node_rve_external,node_rve_refactored,node_rve_composite toneMint
class node_j2_model,node_jax_model,node_jax_utils,node_prnn toneRose
```

## Components

### Macro simulation

- [Macro domain](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/macromodel.py): `macromodel.py`
- [FE² driver](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/fe2_refac.py): `fe2_refac.py`
- [Newton solver](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/customnewtonproblem.py): `customnewtonproblem.py`
- [Loading and solver utilities](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/auxFunctions.py): `auxFunctions.py`

### FE² coupling

- [Quadrature mapping](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/quadrature.py): `quadrature.py`
- [Plotting domain](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/quadrature.py): `quadrature.py`

### RVE models

- [J2 RVE](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_j2_linear_clean.py): `rve_j2_linear_clean.py`
- [J2 RVE variant](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_j2_linear.py): `rve_j2_linear.py`
- [External JAX RVE](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_ext_clean.py): `rve_ext_clean.py`
- [Refactored RVE](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_ext_clean_refac.py): `rve_ext_clean_refac.py`
- [Fiber–matrix RVE](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/rve_fiber_matrix.py): `rve_fiber_matrix.py`

### Constitutive models

- [Plane-stress J2](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/j2_jax.py): `j2_jax.py`
- [J2 material model](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/jax_j2.py): `jax_j2.py`
- [JAX utilities](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/utils_jax.py): `utils_jax.py`
- [PRNN model](https://github.com/marinamaia2021/fe2_fenicsx/blob/main/prnn_jax.py): `prnn_jax.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → FE² driver: runs simulation (evidence: `fe2_refac.py`)
- FE² driver → Macro domain: creates domain (evidence: `fe2_refac.py`)
- FE² driver → Newton solver: uses solver (evidence: `fe2_refac.py`)
- Newton solver → Loading and solver utilities: configures solver (evidence: `customnewtonproblem.py`)
- FE² driver → Quadrature mapping: uses mapping (evidence: `fe2_refac.py`)
- FE² driver → J2 RVE: loads RVE class (evidence: `fe2_refac.py`)
- FE² driver → Fiber–matrix RVE: loads RVE class (evidence: `fe2_refac.py`)
- FE² driver → Refactored RVE: loads RVE class (evidence: `fe2_refac.py`)
- FE² driver → Plotting domain: updates plots (evidence: `fe2_refac.py`)
- J2 RVE → Plane-stress J2: uses material model (evidence: `rve_j2_linear_clean.py`)
- J2 RVE variant → Plane-stress J2: uses material model (evidence: `rve_j2_linear.py`)
- External JAX RVE → J2 material model: uses material model (evidence: `rve_ext_clean.py`)
- Refactored RVE → J2 material model: uses material model (evidence: `rve_ext_clean_refac.py`)
- Fiber–matrix RVE → J2 material model: uses material model (evidence: `rve_fiber_matrix.py`)
- PRNN model → J2 material model: imports model (evidence: `prnn_jax.py`)
