# taewooopark/mumax3-ultrafast architecture

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

- Interactive diagram: https://gitdiagram.com/taewooopark/mumax3-ultrafast
- Repository: https://github.com/taewooopark/mumax3-ultrafast

## Overview

mumax³ ultrafast is a mumax³-compatible micromagnetic simulator, with a native Apple Metal execution backend and an optional desktop app. The main workflow is to provide an `.mx3` script, execute it through the Go engine and GPU backend, and inspect or convert the resulting fields. The repository also includes a standalone result viewer, file conversion tools, and a distributed server. Several backend and desktop-runtime links are documented rather than visible in sampled implementation excerpts, so those links are marked unverified where appropriate.

Main entry points: [`cmd/mumax3/main.go`](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3/main.go) (mumax3 command), [`engine`](https://github.com/taewooopark/mumax3-ultrafast/tree/main/engine) (Physics engine), [`cmd/mumax3-convert/main.go`](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3-convert/main.go) (Format converter), [`apps/desktop/src/App.tsx`](https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/App.tsx) (Desktop workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop workspace<br/>[App.tsx]"]
  node_desktop_api["Desktop API<br/>[api.ts]"]
  node_result_viewer["3D result viewer<br/>[ResultViewer.tsx]"]
end

subgraph group_simulation["Simulation runtime"]
  node_cli["mumax3 command<br/>[main.go]"]
  node_script["Script compiler<br/>[compile.go]"]
  node_engine["Physics engine"]
  node_demag["Demag kernel<br/>[demagkernel.go]"]
  node_server["Distributed server<br/>[main.go]"]
end

subgraph group_backend["GPU execution"]
  node_cuda_api["GPU operations"]
  node_metal["Metal backend"]
end

subgraph group_data["Results and tools"]
  node_result_files["Simulation outputs"]
  node_converter["Format converter<br/>[main.go]"]
  node_ovmf["OVF I/O<br/>[oommf.go]"]
  node_dump["Dump I/O<br/>[read.go]"]
  node_draw["Field rendering<br/>[image.go]"]
end

node_user(("Physicist"))
node_tauri["Desktop runtime"]

node_user -->|"opens workspace"| node_desktop_app
node_user -.->|"runs simulation"| node_cli
node_desktop_app -->|"uses API"| node_desktop_api
node_desktop_app -->|"loads viewer"| node_result_viewer
node_desktop_api -.->|"invokes runtime"| node_tauri
node_cli -->|"compiles scripts"| node_script
node_cli -->|"runs engine"| node_engine
node_cli -->|"initializes GPU"| node_cuda_api
node_engine -->|"uses GPU operations"| node_cuda_api
node_engine -.->|"builds demag kernel"| node_demag
node_cuda_api -.->|"executes on Metal"| node_metal
node_engine -.->|"writes simulation outputs"| node_result_files
node_user -->|"converts results"| node_converter
node_converter -->|"reads and writes OVF"| node_ovmf
node_converter -->|"reads dumps"| node_dump
node_converter -->|"renders images"| node_draw
node_result_viewer -.->|"visualizes OVF results"| node_result_files
node_server -.->|"runs jobs"| node_cli

click node_desktop_app "https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/App.tsx"
click node_desktop_api "https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/api.ts"
click node_result_viewer "https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/components/ResultViewer.tsx"
click node_cli "https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3/main.go"
click node_script "https://github.com/taewooopark/mumax3-ultrafast/blob/main/script/compile.go"
click node_engine "https://github.com/taewooopark/mumax3-ultrafast/tree/main/engine"
click node_demag "https://github.com/taewooopark/mumax3-ultrafast/blob/main/mag/demagkernel.go"
click node_cuda_api "https://github.com/taewooopark/mumax3-ultrafast/tree/main/cuda"
click node_metal "https://github.com/taewooopark/mumax3-ultrafast/blob/main/cuda/metal/metal_runtime_darwin_arm64.cc"
click node_result_files "https://github.com/taewooopark/mumax3-ultrafast/tree/main/engine"
click node_converter "https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3-convert/main.go"
click node_ovmf "https://github.com/taewooopark/mumax3-ultrafast/blob/main/oommf/oommf.go"
click node_dump "https://github.com/taewooopark/mumax3-ultrafast/blob/main/dump/read.go"
click node_draw "https://github.com/taewooopark/mumax3-ultrafast/blob/main/draw/image.go"
click node_server "https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3-server/main.go"

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_desktop_app,node_desktop_api,node_result_viewer toneBlue
class node_cli,node_script,node_engine,node_demag,node_server toneAmber
class node_cuda_api,node_metal toneMint
class node_result_files,node_converter,node_ovmf,node_dump,node_draw toneRose
class node_user,node_tauri toneIndigo
```

## Components

### Desktop experience

- [Desktop workspace](https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Desktop API](https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/api.ts): `apps/desktop/src/api.ts`
- [3D result viewer](https://github.com/taewooopark/mumax3-ultrafast/blob/main/apps/desktop/src/components/ResultViewer.tsx): `apps/desktop/src/components/ResultViewer.tsx`

### Simulation runtime

- [mumax3 command](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3/main.go): `cmd/mumax3/main.go`
- [Script compiler](https://github.com/taewooopark/mumax3-ultrafast/blob/main/script/compile.go): `script/compile.go`
- [Physics engine](https://github.com/taewooopark/mumax3-ultrafast/tree/main/engine): `engine`
- [Demag kernel](https://github.com/taewooopark/mumax3-ultrafast/blob/main/mag/demagkernel.go): `mag/demagkernel.go`
- [Distributed server](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3-server/main.go): `cmd/mumax3-server/main.go`

### GPU execution

- [GPU operations](https://github.com/taewooopark/mumax3-ultrafast/tree/main/cuda): `cuda`
- [Metal backend](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cuda/metal/metal_runtime_darwin_arm64.cc): `cuda/metal/metal_runtime_darwin_arm64.cc`

### Results and tools

- [Simulation outputs](https://github.com/taewooopark/mumax3-ultrafast/tree/main/engine): `engine`
- [Format converter](https://github.com/taewooopark/mumax3-ultrafast/blob/main/cmd/mumax3-convert/main.go): `cmd/mumax3-convert/main.go`
- [OVF I/O](https://github.com/taewooopark/mumax3-ultrafast/blob/main/oommf/oommf.go): `oommf/oommf.go`
- [Dump I/O](https://github.com/taewooopark/mumax3-ultrafast/blob/main/dump/read.go): `dump/read.go`
- [Field rendering](https://github.com/taewooopark/mumax3-ultrafast/blob/main/draw/image.go): `draw/image.go`

### Other components

- **Physicist**
- **Desktop runtime**

## Connections

- Physicist → Desktop workspace: opens workspace (evidence: `README.md`)
- Physicist → mumax3 command: runs simulation (evidence: `README.md`)
- Desktop workspace → Desktop API: uses API (evidence: `apps/desktop/src/App.tsx`)
- Desktop workspace → 3D result viewer: loads viewer (evidence: `apps/desktop/src/App.tsx`)
- Desktop API → Desktop runtime: invokes runtime
- mumax3 command → Script compiler: compiles scripts (evidence: `cmd/mumax3/main.go`)
- mumax3 command → Physics engine: runs engine (evidence: `cmd/mumax3/main.go`)
- mumax3 command → GPU operations: initializes GPU (evidence: `cmd/mumax3/main.go`)
- Physics engine → GPU operations: uses GPU operations (evidence: `engine/average.go`)
- Physics engine → Demag kernel: builds demag kernel
- GPU operations → Metal backend: executes on Metal (evidence: `README.md`)
- Physics engine → Simulation outputs: writes simulation outputs (evidence: `README.md`)
- Physicist → Format converter: converts results (evidence: `cmd/mumax3-convert/main.go`)
- Format converter → OVF I/O: reads and writes OVF (evidence: `cmd/mumax3-convert/main.go`)
- Format converter → Dump I/O: reads dumps (evidence: `cmd/mumax3-convert/main.go`)
- Format converter → Field rendering: renders images (evidence: `cmd/mumax3-convert/main.go`)
- 3D result viewer → Simulation outputs: visualizes OVF results (evidence: `README.md`)
- Distributed server → mumax3 command: runs jobs
