Scientific architecture

VAFT uses a data-centric, layered scientific computing architecture. Scientific kernels favor explicit transformations over hidden mutable state. Side effects are concentrated at the boundaries: machine mapping, persistence, external-code execution, orchestration and the user interface. Configuration and production orchestration are declarative where that helps. Typed data objects and protocols provide the contracts between layers. VAFT favors composition over inheritance, and reusable scientific operations over deep object hierarchies.

This page is a map, not a specification. It introduces no runtime abstraction. Every rule below is already defined, implemented or tracked elsewhere, and each section links to the page that owns it. When this page and an owning page disagree, the owning page wins, and the disagreement is a documentation bug.

Three views of one system

VAFT has three architecture views. Each answers a different question, and they must not be read as one graph.

The dependency explorer is generated from imports. It is not a scientific dependency graph or an architectural verdict: an import that crosses a layer shows where code is, and the normative view says where it should be. The pipeline lineage explorer keeps execution, scientific-reference, validation-evidence and publication relations apart, and shows artifact lineage as a view of its own. A third generated graph, the Scientific ontology explorer, shows what things mean: scientific concepts, the diagnostics that measure them, the Data Dictionary paths that represent them, and the codes, plots and checks that use them. It shares no edges with the other two. Where VAFT’s software comes from is in Software dependencies and External scientific codes.

Scientific ownership

The normative high-level model is the scientific-ownership and maturation architecture (#1645), drawn by vaft.diagram.scientific_ownership_architecture():

In summary:

• Research and Study give the scientific context. Research groups Studies by membership, and neither executes anything.
• A workflow or notebook composes computation for one analysis and incubates new logic.
• Reusable computation produces results and evidence. It comprises data and the database, Formula, Process, Code and learned models.
• Validation interprets that evidence. It is not part of the computation.
• An optional use policy (accept, review, warn, reject, rerun, fallback) decides what a workflow does about a validation outcome. It belongs to the workflow, not to vaft.validation.

Computational layers is the authoritative definition of Formula, Process, Code and the optional Actor, and the zoomed view of the computation band. The figure’s full description is on Diagrams.

Where new functionality belongs

The placement rule follows meaning, not implementation technology or prestige.

Ask the questions in this order:

1. Is it an explicit mathematical relation? → Formula.
2. Is it a reusable computation implemented inside VAFT? → Process.
3. Does it wrap an independent scientific solver? → Code.
4. Is it scientific state or a portable representation? → Data, or the owning domain’s representation.
5. Does it map machine-specific acquisition or configuration? → Machine mapping.
6. Does it assess evidence or scientific applicability? → Validation.
7. Does it retrieve, persist or publish data? → Database.
8. Does it adapt results for presentation or render them? → Plot.
9. Is it orchestration for one study? → keep it in the workflow or notebook.

Logic written in a workflow graduates to its semantic owner once it is reused or copied elsewhere, needs its own tests, defines a stable operation, or enters routine production (#1642, drawn under #1645). The workflow graduation audit lists the candidates found so far.

Some facts are not reasons for an abstraction:

• Several codes belonging to one broad physics domain do not justify an Actor. An Actor needs the same scientific operation and a contract that makes comparison meaningful (When an Actor is justified).
• A function taking an ODS does not make it belong to OMAS. It belongs to whatever it computes.
• Logic first written in a workflow is not owned by that workflow permanently.

Programming model

VAFT is neither a purely functional system nor an inheritance-heavy object framework. Its tendency is a transformation-oriented scientific core with imperative boundaries.

Comparatively explicit computational regions include vaft.formula, most vaft.process operations, typed equilibrium representations, plot view models and validation value objects.

Side effects are expected in vaft.machine_mapping (reading raw machine data), vaft.database (persistence and publication), vaft.code (writing inputs and launching external programs), production orchestration and the GUI. Side effects inside vaft.process are the exception rather than the rule.

Assessment follows the same rule from the other side. A process returns its result, and assessment is a separate optional call over that result (the rule Credibility and applicability protects).

Selective object orientation

VAFT has many classes without being primarily object-oriented. Each class has one of a few roles:

Use an object when identity, structured state, validation, configuration or an interface contract benefits from it. Do not turn scientific operations into mutable domain-object hierarchies for uniformity. Prefer composition over inheritance.

Typed boundaries and intermediate representations

A growing pattern is an explicit typed representation between an interoperability container and an algorithm:

ODS / IDS               → EquilibriumData → equilibrium algorithms
scientific profile data → GACODEProfile   → TGLF / NEO / CGYRO adapters
ODS / IDS / database    → plot view model → renderer

This does not ban ODS or IDS inputs. A complex domain algorithm should not depend on an opaque universal container when its scientific inputs can be stated explicitly. Equilibrium representations describes the equilibrium case.

Scientific data semantics

VAFT is data-centric in the sense of a standardized scientific state: state is standardized, explicit transformations act on it, and the result or evidence goes on to validation, persistence or presentation. It is not Data-Oriented Design in the memory-layout or cache-locality sense, and memory layout is not its organizing principle.

VAFT organizes scientific state according to IMAS semantics. Concrete in-memory and interoperability representations may evolve independently of that semantic contract.

ODS is therefore today’s representation, not the permanent centre of the architecture. The DD core is developed outside develop (#1127), and the documentation moves from ODS-first to DD/DDView-first usage under #1133.

Machine differences are absorbed at the mapping boundary (Data access and IMAS). Everything above it sees standardized state:

Composition and orchestration

There is no general VAFT Workflow object model, and none is implied here. The repository’s workflow/ tree holds concrete scripts, studies and Snakemake pipelines. Production orchestration is DAG-based without making Workflow a public domain abstraction.

Implementation status

A box in a diagram does not mean a public Python class exists. This table says which concepts do.

Non-goals

These follow existing decisions and add none. VAFT is not meant to become:

• an inheritance-driven ontology of all fusion physics;
• one mutable Shot object that owns every possible operation;
• a mandatory Actor layer around every solver;
• a general workflow engine inside the Python API;
• a system where validation and acceptance policy are indistinguishable;
• a system where storage or database layers own scientific interpretation;
• a system where every scientific routine operates directly on one universal container;
• a second scientific hierarchy organized around ML implementation technology.

Related reference

• Computational layers: Formula, Process, Code and Actor.
• Credibility and applicability: computation, evidence, validation and applicability.
• Plasma models, orderings, and scales and Asymptotic orderings: what physical model a computation represents. This page says only where it lives.
• Fusion data structure and IMAS concepts: the IMAS data model.
• Database and data sources: retrieval and persistence.
• Research domains: the research modes and physics domains this architecture serves, and how they meet.
• Diagrams: every canonical architecture and concept figure.