# thisismeamir/kosmic architecture

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

- Interactive diagram: https://gitdiagram.com/thisismeamir/kosmic
- Repository: https://github.com/thisismeamir/kosmic

## Overview

Kosmic is an early-development lattice field theory simulation framework, with Abelian Higgs as its intended primary theory and a separate snapshot augmentation pipeline. The principal workflow is to define a theory and metric, evolve lattice fields, and save snapshots; clustering and recombination can then synthesize configurations with provenance. The README documents CUDA, AMR, HDF5 storage, and augmentation capabilities, but sampled code does not show their runtime wiring, so those connections are omitted. Several listed implementation areas are still placeholders.

Main entry points: [`core/integrator/include/kosmic/integrator/LeapFrogIntegrator.hpp`](https://github.com/thisismeamir/kosmic/blob/master/core/integrator/include/kosmic/integrator/LeapFrogIntegrator.hpp) (Leapfrog evolution), [`templates/free_scalar/include/kosmic/templates/free_scalar/FreeScalarDynamics.hpp`](https://github.com/thisismeamir/kosmic/blob/master/templates/free_scalar/include/kosmic/templates/free_scalar/FreeScalarDynamics.hpp) (Free scalar model), [`core/theory/fields/include/kosmic/theory/fields/Scalarfield.hpp`](https://github.com/thisismeamir/kosmic/blob/master/core/theory/fields/include/kosmic/theory/fields/Scalarfield.hpp) (Scalar building block), [`core/field/include/kosmic/field/Field.hpp`](https://github.com/thisismeamir/kosmic/blob/master/core/field/include/kosmic/field/Field.hpp) (Lattice fields)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Simulation core"]
  node_api["Public API"]
  node_field["Lattice fields<br/>[Field.hpp]"]
  node_boundary["Periodic access"]
  node_geometry["Metric models<br/>[Metric.hpp]"]
  node_numerics["Finite differences"]
  node_integrator["Leapfrog evolution"]
  node_cpu["CPU backend"]
  node_cuda["CUDA backend"]
  node_amr["Adaptive refinement"]
end

subgraph group_theory["Theory models"]
  node_contract["Theory contract"]
  node_scalar["Scalar building block<br/>[Scalarfield.hpp]"]
  node_free["Free scalar model"]
  node_abelian["Abelian Higgs"]
end

subgraph group_storage["Snapshots"]
  node_schema["Snapshot schema"]
  node_manager[("Dataset manager")]
end

subgraph group_augment["Augmentation"]
  node_cluster["Lattice clustering"]
  node_recombine["Region recombination"]
  node_provenance["Lineage metadata"]
end

node_researcher(("Simulation user"))

node_researcher -->|"uses"| node_api
node_boundary -->|"wraps access"| node_field
node_numerics -->|"samples neighbors"| node_boundary
node_scalar -->|"computes Laplacian"| node_numerics
node_scalar -->|"reads and accumulates"| node_field
node_free -->|"uses contribution"| node_scalar
node_integrator -->|"evaluates dynamics"| node_free
node_integrator -->|"passes metric"| node_geometry
node_integrator -->|"advances fields"| node_field
node_free -->|"implements parameters"| node_contract
node_abelian -.->|"implements theory"| node_contract
node_manager -.->|"uses schema"| node_schema
node_cluster -.->|"provides regions"| node_recombine
node_recombine -.->|"records lineage"| node_provenance

click node_api "https://github.com/thisismeamir/kosmic/tree/master/core/api"
click node_field "https://github.com/thisismeamir/kosmic/blob/master/core/field/include/kosmic/field/Field.hpp"
click node_boundary "https://github.com/thisismeamir/kosmic/blob/master/core/field/include/kosmic/field/PeriodicAccessor.hpp"
click node_geometry "https://github.com/thisismeamir/kosmic/blob/master/core/geometry/include/kosmic/geometry/Metric.hpp"
click node_numerics "https://github.com/thisismeamir/kosmic/blob/master/core/math/include/kosmic/math/Finitedifference.hpp"
click node_integrator "https://github.com/thisismeamir/kosmic/blob/master/core/integrator/include/kosmic/integrator/LeapFrogIntegrator.hpp"
click node_cpu "https://github.com/thisismeamir/kosmic/tree/master/core/backend/cpu"
click node_cuda "https://github.com/thisismeamir/kosmic/tree/master/core/backend/cuda"
click node_amr "https://github.com/thisismeamir/kosmic/tree/master/core/amr"
click node_contract "https://github.com/thisismeamir/kosmic/blob/master/core/theory/interface/include/kosmic/theory/TheoryInterface.hpp"
click node_scalar "https://github.com/thisismeamir/kosmic/blob/master/core/theory/fields/include/kosmic/theory/fields/Scalarfield.hpp"
click node_free "https://github.com/thisismeamir/kosmic/blob/master/templates/free_scalar/include/kosmic/templates/free_scalar/FreeScalarDynamics.hpp"
click node_abelian "https://github.com/thisismeamir/kosmic/tree/master/core/theory/abelian_higgs"
click node_schema "https://github.com/thisismeamir/kosmic/tree/master/storage/schema"
click node_manager "https://github.com/thisismeamir/kosmic/tree/master/storage/manager"
click node_cluster "https://github.com/thisismeamir/kosmic/tree/master/augment/cluster"
click node_recombine "https://github.com/thisismeamir/kosmic/tree/master/augment/recombine"
click node_provenance "https://github.com/thisismeamir/kosmic/tree/master/augment/provenance"

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_api,node_field,node_boundary,node_geometry,node_numerics,node_integrator,node_cpu,node_cuda,node_amr,node_researcher toneBlue
class node_contract,node_scalar,node_free,node_abelian toneAmber
class node_schema,node_manager toneMint
class node_cluster,node_recombine,node_provenance toneRose
```

## Components

### Simulation core

- [Public API](https://github.com/thisismeamir/kosmic/tree/master/core/api): `core/api`
- [Lattice fields](https://github.com/thisismeamir/kosmic/blob/master/core/field/include/kosmic/field/Field.hpp): `core/field/include/kosmic/field/Field.hpp`
- [Periodic access](https://github.com/thisismeamir/kosmic/blob/master/core/field/include/kosmic/field/PeriodicAccessor.hpp): `core/field/include/kosmic/field/PeriodicAccessor.hpp`
- [Metric models](https://github.com/thisismeamir/kosmic/blob/master/core/geometry/include/kosmic/geometry/Metric.hpp): `core/geometry/include/kosmic/geometry/Metric.hpp`
- [Finite differences](https://github.com/thisismeamir/kosmic/blob/master/core/math/include/kosmic/math/Finitedifference.hpp): `core/math/include/kosmic/math/Finitedifference.hpp`
- [Leapfrog evolution](https://github.com/thisismeamir/kosmic/blob/master/core/integrator/include/kosmic/integrator/LeapFrogIntegrator.hpp): `core/integrator/include/kosmic/integrator/LeapFrogIntegrator.hpp`
- [CPU backend](https://github.com/thisismeamir/kosmic/tree/master/core/backend/cpu): `core/backend/cpu`
- [CUDA backend](https://github.com/thisismeamir/kosmic/tree/master/core/backend/cuda): `core/backend/cuda`
- [Adaptive refinement](https://github.com/thisismeamir/kosmic/tree/master/core/amr): `core/amr`

### Theory models

- [Theory contract](https://github.com/thisismeamir/kosmic/blob/master/core/theory/interface/include/kosmic/theory/TheoryInterface.hpp): `core/theory/interface/include/kosmic/theory/TheoryInterface.hpp`
- [Scalar building block](https://github.com/thisismeamir/kosmic/blob/master/core/theory/fields/include/kosmic/theory/fields/Scalarfield.hpp): `core/theory/fields/include/kosmic/theory/fields/Scalarfield.hpp`
- [Free scalar model](https://github.com/thisismeamir/kosmic/blob/master/templates/free_scalar/include/kosmic/templates/free_scalar/FreeScalarDynamics.hpp): `templates/free_scalar/include/kosmic/templates/free_scalar/FreeScalarDynamics.hpp`
- [Abelian Higgs](https://github.com/thisismeamir/kosmic/tree/master/core/theory/abelian_higgs): `core/theory/abelian_higgs`

### Snapshots

- [Snapshot schema](https://github.com/thisismeamir/kosmic/tree/master/storage/schema): `storage/schema`
- [Dataset manager](https://github.com/thisismeamir/kosmic/tree/master/storage/manager): `storage/manager`

### Augmentation

- [Lattice clustering](https://github.com/thisismeamir/kosmic/tree/master/augment/cluster): `augment/cluster`
- [Region recombination](https://github.com/thisismeamir/kosmic/tree/master/augment/recombine): `augment/recombine`
- [Lineage metadata](https://github.com/thisismeamir/kosmic/tree/master/augment/provenance): `augment/provenance`

### Other components

- **Simulation user**

## Connections

- Simulation user → Public API: uses
- Periodic access → Lattice fields: wraps access
- Finite differences → Periodic access: samples neighbors
- Scalar building block → Finite differences: computes Laplacian
- Scalar building block → Lattice fields: reads and accumulates
- Free scalar model → Scalar building block: uses contribution
- Leapfrog evolution → Free scalar model: evaluates dynamics
- Leapfrog evolution → Metric models: passes metric
- Leapfrog evolution → Lattice fields: advances fields
- Free scalar model → Theory contract: implements parameters
- Abelian Higgs → Theory contract: implements theory
- Dataset manager → Snapshot schema: uses schema
- Lattice clustering → Region recombination: provides regions
- Region recombination → Lineage metadata: records lineage