# williamhunter/topy architecture

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

- Interactive diagram: https://gitdiagram.com/williamhunter/topy
- Repository: https://github.com/williamhunter/topy

## Overview

##### Project Type and Purpose
- The project is a specialized computational tool designed to solve topology optimization problems related to stiffness (compliance), mechanism synthesis, and heat conduction in 2D/3D.
- It supports two kinds of problem definitions: a text-based “TPD” file and a Python dictionary configuration, making it flexible for both command-line users and Python developers.

##### Analyzing the File Structure
- Core Library (“topy” directory):
- Contains key modules such as topy/topology.py (defining the Topology class), topy/optimisation.py (running the optimization routines), topy/elements.py (defining finite element data), and topy/visualisation.py (for exporting results in VTK/PNG).
- The “topy/data” subdirectory houses precomputed stiffness matrices/material constants and related data needed for the optimization.
- Utility functions for parsing and additional support are located in topy/parser.py and topy/utils.py.
- Examples (“examples” directory):
- Provides several example TPD files for different problem scenarios (arm, cantilever, dogleg, heat, inverter, etc.), which illustrate the use cases of ToPy.
- Command-Line and Script Interfaces:
- The “scripts” directory (with optimise.py) presents the command-line entry point for solving problems, while the examples in the README show usage via Python scripts.
- Testing, Deployment, and Documentation:
- The “tests” folder ensures the correctness of examples.
- GitHub workflows (in .github/workflows) and setup.py facilitate CI/CD and package deployment.
- Additional documentation is provided in the “docs” directory and README files, including installation guides and usage instructions.

a. Main Components:
- Input/Configuration Component: Illustrate how a problem is defined (via TPD text file or a Python configuration dictionary) and then loaded by the Topology class.
- Core Optimization Engine:
- Core Classes (Topology, Optimisation, and Elements modules)
- Data Handling: The “data” module storing stiffness matrices and material constraints.
- Visualization Component: The topy/visualisation.py module that translates computational results into PNG or VTK files.
- Command-Line Interface: The scripts (e.g., optimise.py) and support for direct user command-line calls.
- Examples and Templates: Shown in separate directories that demonstrate problem definitions and usage.
- Supporting Infrastructure:
- Testing Module: The tests for validating functionality.
- Build/Deployment: Setup.py, GitHub workflows, and dependency management (e.g., conda.yml).

b. Relationships and Interactions:
- Data flows from the “Input/Configuration Component” into the Topology class.
- The Topology class uses the “Data Module” for retrieving material properties.
- The “Optimization Engine” (including optimisation.py and elements.py) receives inputs from Topology and computes the optimal topology.
- The Visualization module receives output from the optimization engine to generate images or VTK files.
- The command-line script (in scripts/optimise.py) acts as an orchestrator that pulls configuration, runs optimization, and launches visualization.
- Testing and CI/CD components ensure that each module (input parsing, computation, visualization) is working correctly.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Each module specializes in one part of the process (input processing, optimization, visualization) ensuring modularity.
- Layered Architecture: From external interfaces (command line, TPD files) down to internal computational routines and data management.
- Extensibility: The use of configuration dictionaries and templating (in the templates folder) suggests an approach designed for easy customization.

d. Relevant Technologies, Frameworks, or Libraries:
- Python is the primary language.
- The project supports both Python 2 (stable release) and Python 3 (latest unstable version).
- For visualization, exported VTK files can be rendered using Mayavi or ParaView; additionally, ImageMagick is recommended for creating animations.
- GitHub Actions for continuous integration and publishing use YAML configuration files (.github/workflows).

##### Essential Elements
- Clear labels for each component (e.g., “Input Processor (TPD/Config Parser)”, “Topology Class & Optimization Engine”, “Data Module”, “Visualization Module”, “Command-Line Interface”, “Testing/CI”, “Deployment”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Input & CLI"
        A1("Input/Configuration"):::input
        A2("Command-Line Interface"):::cli
    end

    %% Core Optimization Engine
    subgraph "Core Optimization Engine"
        B1("Topology Class"):::core
        B2("Optimisation Module"):::core
        B3("Elements Module"):::core
    end

    %% Data Management
    subgraph "Data Management"
        C("Material Properties Data"):::data
    end

    %% Visualization
    subgraph "Visualization"
        D("Visualization Module"):::vis
    end

    %% Examples & Templates
    subgraph "Examples & Templates"
        E1("Examples"):::example
        E2("Templates"):::example
    end

    %% Testing
    subgraph "Testing"
        F("Testing Module"):::test
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        G1("Package Setup"):::build
        G2("CI/CD Workflows"):::build
    end

    %% Connections
    A1 -->|"config"| B1
    C -->|"material"| B1
    B1 -->|"triggers"| B2
    B1 -->|"triggers"| B3
    B2 -->|"results"| D
    B3 -->|"results"| D

    A2 -->|"orchestrates"| A1
    A2 -->|"orchestrates"| B1
    A2 -->|"orchestrates"| D

    E1 -->|"sample_config"| A1
    E2 -->|"template_config"| A1

    F -->|"validates"| A1
    F -->|"validates"| B1
    F -->|"validates"| D

    G1 -->|"setup"| A2
    G1 -->|"setup"| B1
    G1 -->|"setup"| D

    G2 -->|"deploys"| A2
    G2 -->|"deploys"| B1
    G2 -->|"deploys"| D

    %% Click Events
    click A1 "https://github.com/williamhunter/topy/blob/master/topy/parser.py"
    click B1 "https://github.com/williamhunter/topy/blob/master/topy/topology.py"
    click B2 "https://github.com/williamhunter/topy/blob/master/topy/optimisation.py"
    click B3 "https://github.com/williamhunter/topy/blob/master/topy/elements.py"
    click C "https://github.com/williamhunter/topy/tree/master/topy/data/"
    click D "https://github.com/williamhunter/topy/blob/master/topy/visualisation.py"
    click A2 "https://github.com/williamhunter/topy/blob/master/scripts/optimise.py"
    click E1 "https://github.com/williamhunter/topy/tree/master/examples/"
    click E2 "https://github.com/williamhunter/topy/tree/master/templates/"
    click F "https://github.com/williamhunter/topy/blob/master/tests/test_examples.py"
    click G1 "https://github.com/williamhunter/topy/blob/master/setup.py"
    click G2 "https://github.com/williamhunter/topy/tree/master/.github/workflows/"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cli fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#ffc,stroke:#333,stroke-width:2px;
    classDef data fill:#cfc,stroke:#333,stroke-width:2px;
    classDef vis fill:#fcf,stroke:#333,stroke-width:2px;
    classDef example fill:#cff,stroke:#333,stroke-width:2px;
    classDef test fill:#fdd,stroke:#333,stroke-width:2px;
    classDef build fill:#ddd,stroke:#333,stroke-width:2px;
```
