# luozf14/mdmtrace architecture

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

- Interactive diagram: https://gitdiagram.com/luozf14/mdmtrace
- Repository: https://github.com/luozf14/mdmtrace

## Overview

MDMTrace supports a user workflow from configured ion and ray inputs through either legacy RAYTRACE or generated field-map transport, producing trace results for comparison or ion-optical fitting. Field tuning and map visualization are additional product branches. The README documents the major tools and map format; sampled source confirms map generation, standalone transport, and comparison behavior. Some executable internals were not sampled, so links for those branches reflect documented capabilities rather than inferred implementation details.

Main entry points: [`config`](https://github.com/luozf14/mdmtrace/tree/main/config) (JSON configs), [`Compare.cpp`](https://github.com/luozf14/mdmtrace/blob/main/Compare.cpp) (Transport comparison), [`src/MdmTrace.cpp`](https://github.com/luozf14/mdmtrace/blob/main/src/MdmTrace.cpp) (Legacy transport), [`src/MdmFieldMapGenerator.cpp`](https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapGenerator.cpp) (Map generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and tuning"]
  node_configs["JSON configs"]
  node_raydeck["RAYTRACE deck<br/>[rayin.dat]"]
  node_fieldtune["Field tuning<br/>[FindMdmField.cpp]"]
end

subgraph group_legacy["Legacy transport"]
  node_ion["Ion model<br/>[MdmIon.cpp]"]
  node_legacytrace["Legacy transport<br/>[MdmTrace.cpp]"]
  node_fortran["RAYTRACE routines<br/>[RAYTKIN1.F]"]
  node_legacyrunner["Legacy trace tool"]
end

subgraph group_maps["Field maps"]
  node_interop["Field bridge"]
  node_generator["Map generator"]
  node_maplib["Map reader<br/>[MdmFieldMap.cpp]"]
  node_mapstore[("Field-map files")]
  node_maptrace["Map transport"]
  node_maprunner["Map trace tool"]
end

subgraph group_analysis["Analysis tools"]
  node_compare["Transport comparison<br/>[Compare.cpp]"]
  node_ionoptics["Ion-optics fitting"]
  node_root["ROOT"]
  node_results["Trace and fit results"]
end

subgraph group_visuals["Visualization"]
  node_plots["Field-map plots"]
end

node_operator(("MDM user"))

node_operator -->|"sets parameters"| node_configs
node_operator -->|"tunes field"| node_fieldtune
node_operator -->|"runs tracing"| node_legacyrunner
node_operator -->|"generates maps"| node_generator
node_operator -->|"runs tracing"| node_maprunner
node_operator -->|"compares models"| node_compare
node_operator -->|"fits optics"| node_ionoptics
node_operator -->|"views fields"| node_plots
node_configs -->|"configures"| node_fieldtune
node_configs -->|"configures"| node_generator
node_configs -->|"configures"| node_legacyrunner
node_configs -->|"configures"| node_maprunner
node_configs -->|"configures"| node_compare
node_configs -->|"configures"| node_ionoptics
node_raydeck -->|"supplies deck"| node_fortran
node_fieldtune -->|"tunes model"| node_legacytrace
node_legacyrunner -->|"traces rays"| node_legacytrace
node_legacytrace -->|"uses ion model"| node_ion
node_legacytrace -->|"calls routines"| node_fortran
node_generator -->|"samples fields"| node_legacytrace
node_generator -->|"calls field bridge"| node_interop
node_generator -->|"writes maps"| node_mapstore
node_maprunner -->|"traces rays"| node_maptrace
node_maprunner -->|"uses map reader"| node_maplib
node_maptrace -->|"interpolates maps"| node_maplib
node_maptrace -->|"loads maps"| node_mapstore
node_compare -->|"runs legacy model"| node_legacytrace
node_compare -->|"runs map model"| node_maptrace
node_compare -->|"writes comparison"| node_results
node_ionoptics -->|"traces fit rays"| node_maptrace
node_ionoptics -.->|"solves with SVD"| node_root
node_ionoptics -->|"reports fit"| node_results
node_compare -.->|"plots results"| node_root
node_plots -->|"reads maps"| node_mapstore

click node_configs "https://github.com/luozf14/mdmtrace/tree/main/config"
click node_raydeck "https://github.com/luozf14/mdmtrace/blob/main/dat/rayin.dat"
click node_fieldtune "https://github.com/luozf14/mdmtrace/blob/main/FindMdmField.cpp"
click node_ion "https://github.com/luozf14/mdmtrace/blob/main/src/MdmIon.cpp"
click node_legacytrace "https://github.com/luozf14/mdmtrace/blob/main/src/MdmTrace.cpp"
click node_fortran "https://github.com/luozf14/mdmtrace/blob/main/src/RAYTKIN1.F"
click node_legacyrunner "https://github.com/luozf14/mdmtrace/blob/main/MdmTraceExample.cpp"
click node_interop "https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapInterop.F90"
click node_generator "https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapGenerator.cpp"
click node_maplib "https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMap.cpp"
click node_maptrace "https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapTrace.cpp"
click node_maprunner "https://github.com/luozf14/mdmtrace/blob/main/MdmFieldMapTraceExample.cpp"
click node_compare "https://github.com/luozf14/mdmtrace/blob/main/Compare.cpp"
click node_ionoptics "https://github.com/luozf14/mdmtrace/blob/main/GenerateIonOptics.cpp"
click node_plots "https://github.com/luozf14/mdmtrace/tree/main/visual"

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_configs,node_raydeck,node_fieldtune,node_operator toneBlue
class node_ion,node_legacytrace,node_fortran,node_legacyrunner toneAmber
class node_interop,node_generator,node_maplib,node_mapstore,node_maptrace,node_maprunner toneMint
class node_compare,node_ionoptics,node_root,node_results toneRose
class node_plots toneIndigo
```

## Components

### Inputs and tuning

- [JSON configs](https://github.com/luozf14/mdmtrace/tree/main/config): `config`
- [RAYTRACE deck](https://github.com/luozf14/mdmtrace/blob/main/dat/rayin.dat): `dat/rayin.dat`
- [Field tuning](https://github.com/luozf14/mdmtrace/blob/main/FindMdmField.cpp): `FindMdmField.cpp`

### Legacy transport

- [Ion model](https://github.com/luozf14/mdmtrace/blob/main/src/MdmIon.cpp): `src/MdmIon.cpp`
- [Legacy transport](https://github.com/luozf14/mdmtrace/blob/main/src/MdmTrace.cpp): `src/MdmTrace.cpp`
- [RAYTRACE routines](https://github.com/luozf14/mdmtrace/blob/main/src/RAYTKIN1.F): `src/RAYTKIN1.F`
- [Legacy trace tool](https://github.com/luozf14/mdmtrace/blob/main/MdmTraceExample.cpp): `MdmTraceExample.cpp`

### Field maps

- [Field bridge](https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapInterop.F90): `src/MdmFieldMapInterop.F90`
- [Map generator](https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapGenerator.cpp): `src/MdmFieldMapGenerator.cpp`
- [Map reader](https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMap.cpp): `src/MdmFieldMap.cpp`
- **Field-map files**
- [Map transport](https://github.com/luozf14/mdmtrace/blob/main/src/MdmFieldMapTrace.cpp): `src/MdmFieldMapTrace.cpp`
- [Map trace tool](https://github.com/luozf14/mdmtrace/blob/main/MdmFieldMapTraceExample.cpp): `MdmFieldMapTraceExample.cpp`

### Analysis tools

- [Transport comparison](https://github.com/luozf14/mdmtrace/blob/main/Compare.cpp): `Compare.cpp`
- [Ion-optics fitting](https://github.com/luozf14/mdmtrace/blob/main/GenerateIonOptics.cpp): `GenerateIonOptics.cpp`
- **ROOT**
- **Trace and fit results**

### Visualization

- [Field-map plots](https://github.com/luozf14/mdmtrace/tree/main/visual): `visual`

### Other components

- **MDM user**

## Connections

- MDM user → JSON configs: sets parameters
- MDM user → Field tuning: tunes field
- MDM user → Legacy trace tool: runs tracing
- MDM user → Map generator: generates maps
- MDM user → Map trace tool: runs tracing
- MDM user → Transport comparison: compares models
- MDM user → Ion-optics fitting: fits optics
- MDM user → Field-map plots: views fields
- JSON configs → Field tuning: configures
- JSON configs → Map generator: configures
- JSON configs → Legacy trace tool: configures
- JSON configs → Map trace tool: configures
- JSON configs → Transport comparison: configures
- JSON configs → Ion-optics fitting: configures
- RAYTRACE deck → RAYTRACE routines: supplies deck
- Field tuning → Legacy transport: tunes model
- Legacy trace tool → Legacy transport: traces rays
- Legacy transport → Ion model: uses ion model
- Legacy transport → RAYTRACE routines: calls routines
- Map generator → Legacy transport: samples fields
- Map generator → Field bridge: calls field bridge
- Map generator → Field-map files: writes maps
- Map trace tool → Map transport: traces rays
- Map trace tool → Map reader: uses map reader
- Map transport → Map reader: interpolates maps
- Map transport → Field-map files: loads maps
- Transport comparison → Legacy transport: runs legacy model
- Transport comparison → Map transport: runs map model
- Transport comparison → Trace and fit results: writes comparison
- Ion-optics fitting → Map transport: traces fit rays
- Ion-optics fitting → ROOT: solves with SVD
- Ion-optics fitting → Trace and fit results: reports fit
- Transport comparison → ROOT: plots results
- Field-map plots → Field-map files: reads maps