# ritchie46/anastruct architecture

> Architecture diagram of the GitHub repository ritchie46/anastruct, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ritchie46/anastruct
- Repository: https://github.com/ritchie46/anastruct

## Overview

##### Project type and purpose
- Type: Python library (with optional Cython extensions) for structural analysis (FEM).
- Purpose: Provide an API (SystemElements, basic routines) to build 2D structural models, assemble & solve them, post-process results, and plot outcomes.

##### File structure
Top‐level:
- anastruct/        ← core package
– basic.py        ← simple non-FEM routines & helper functions
– cython/         ← performance modules implemented in Cython
– fem/            ← main FEM logic
- cython/       ← Cython speedups for assembly & element routines
- elements.py   ← element definitions (beam, truss)
- system_components/ ← assembly, solver, utility classes
- postprocess.py← result extraction
- plotter/      ← Matplotlib & null plotting backends
- util/         ← load & envelope utilities
– material/       ← material profiles & unit conversions (CSV data)
– sectionbase/    ← section database & property calculators (XML)
– types.py, vertex.py ← shared data types
- doc/              ← Sphinx documentation sources
- tests/            ← unit, E2E, benchmark tests
- build_cython_ext.py, pyproject.toml ← build & packaging
- .github/ workflows ← CI/CD.

##### Pull insights from the README
- The public API centers on SystemElements.
- Supports pure‐Python and Cython‐accelerated code paths.
- Relies on external databases (steel sections) and Matplotlib for plotting.

##### Main components & their interactions

A. User/API Layer
- “SystemElements” class (anastruct/basic.py + fem/system.py)
- Example scripts (in doc/examples & tests)

B. Core Domain Logic
1. Geometry & Model Builder
– Node & element data structures (vertex.py, types.py)
– Element definitions (fem/elements.py)
2. Solver & Assembly
– Assembly routines (fem/system_components/assembly.py)
– Solver (fem/system_components/solver.py)
– Utilities (fem/system_components/util.py)
3. Material & Section Data
– Material profiles (material/profile.py, units.py)
– Section database (sectionbase/*.xml via sectionbase/sectionbase.py)

C. Performance / Extension Layer
- Cython modules (anastruct/cython and anastruct/fem/cython)
– Accelerated stiffness & element routines
– Bound to Python classes via .pxd/.pyx

D. Post-Processing & Visualization
- Postprocess (fem/postprocess.py) calculates forces/moments/displacements
- Plotter backends (fem/plotter/mpl.py, null.py)

E. External Services & Tools
- Matplotlib (plotting)
- CI/CD (GitHub Actions workflows)
- Sphinx (docs)
- PyPI (distribution)

##### Relationships & data flow
1. User code → calls SystemElements (public API).
2. SystemElements → builds internal model (nodes/elements).
3. Model → passes to Assembly → creates global stiffness matrix.
4. Solver → applies boundary conditions, solves linear/nonlinear system.
5. Postprocess → extracts result vectors.
7. Data sources (material/sectionbase) feed properties into model.
8. Cython modules can be invoked at steps 3 & 4 for speed.

##### Architectural patterns & design principles
- Layered architecture (API → Core → Data → Performance → I/O).
- Clear separation of concerns: building, solving, post-processing, plotting.
- Plugin/extension points: multiple plotter backends; pure-Python vs Cython code paths.
- Data‐driven: element & material databases loaded from external files.

##### Detail without clutter
- External dependencies separately (Matplotlib, CI, docs).
- Don’t over‐fragment—focus on the main logical components and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        SystemElements["SystemElements"]:::api
        ExampleScripts["Example Scripts"]:::api
    end

    %% Core Domain Logic
    subgraph "Core Domain Logic"
        subgraph "Model Builder"
            Geometry["Geometry & Model Builder"]:::core
        end
        subgraph "Element Definitions"
            Elements["Element Definitions"]:::core
        end
        subgraph "Solver & Assembly"
            Assembly["Assembly Routines"]:::core
            Solver["Solver"]:::core
            Util["Assembly Utilities"]:::core
        end
        subgraph "Post-Processing & Visualization"
            Postprocess["Post-Processing"]:::core
            PlotterMPL["Plotter (MPL)"]:::core
            PlotterNull["Plotter (Null)"]:::core
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        MaterialProfiles["Material Profiles & Units"]:::data
        SectionDB["Section Database & Properties"]:::data
    end

    %% Extension Layer
    subgraph "Extension Layer"
        CythonCore["Cython Acceleration (Core)"]:::ext
        CythonFEM["Cython Acceleration (FEM)"]:::ext
    end

    %% External Tools & Services
    subgraph "External Tools & Services"
        Matplotlib["Matplotlib"]:::io
        CI["CI/CD (GitHub Workflows)"]:::io
        Docs["Sphinx Documentation"]:::io
        PyPI["PyPI Distribution"]:::io
    end

    %% Connections
    SystemElements -->|"builds model"| Geometry
    SystemElements -->|"defines elements"| Elements
    SystemElements -->|"initiates assembly"| Assembly
    Assembly -->|"uses solver routines"| Solver
    Assembly -->|"calls utility functions"| Util
    Solver -->|"produces solution"| Postprocess
    Postprocess -->|"renders via MPL"| PlotterMPL
    Postprocess -->|"renders via null backend"| PlotterNull
    MaterialProfiles -->|"provides material data"| SystemElements
    SectionDB -->|"provides section data"| SystemElements
    CythonCore -->|"accelerates assembly"| Assembly
    CythonFEM -->|"accelerates elements"| Solver
    PlotterMPL -->|"plots via"| Matplotlib
    CI -->|"validates code"| SystemElements
    Docs -->|"documents API"| SystemElements
    PyPI -->|"publishes package"| SystemElements

    %% Click Events
    click SystemElements "https://github.com/ritchie46/anastruct/blob/master/anastruct/basic.py"
    click ExampleScripts "https://github.com/ritchie46/anastruct/tree/master/anastruct/fem/examples/"
    click Geometry "https://github.com/ritchie46/anastruct/blob/master/anastruct/vertex.py"
    click Elements "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/elements.py"
    click Assembly "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/system_components/assembly.py"
    click Solver "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/system_components/solver.py"
    click Util "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/system_components/util.py"
    click Postprocess "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/postprocess.py"
    click PlotterMPL "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/plotter/mpl.py"
    click PlotterNull "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/plotter/null.py"
    click MaterialProfiles "https://github.com/ritchie46/anastruct/blob/master/anastruct/material/profile.py"
    click SectionDB "https://github.com/ritchie46/anastruct/blob/master/anastruct/sectionbase/sectionbase.py"
    click CythonCore "https://github.com/ritchie46/anastruct/blob/master/anastruct/cython/basic.py"
    click CythonFEM "https://github.com/ritchie46/anastruct/blob/master/anastruct/fem/cython/celements.pyx"
    click CI "https://github.com/ritchie46/anastruct/tree/master/.github/workflows/"
    click Docs "https://github.com/ritchie46/anastruct/tree/master/doc/source/"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#000;
    classDef core fill:#D0FFD6,stroke:#000;
    classDef data fill:#FFDFA8,stroke:#000;
    classDef ext fill:#E6D0FF,stroke:#000;
    classDef io fill:#D8D8D8,stroke:#000;
```
