📚 Course ContentsChapter 3 Metadata schemas for CAE

3. Metadata schemas for CAE

In a CAE experiment tracking system, the metadata schema is the contract that defines what a "run" actually means. Without a disciplined schema, two analysts can run nominally identical simulations and produce records that cannot be compared, filtered, or reproduced. This section defines a practical, extensible metadata schema for structural and multiphysics CAE runs, covering solver settings, mesh attributes, boundary conditions, material models, and convergence criteria, and shows how to encode it so that a model registry can index and diff runs reliably.

Why a Schema, Not Free-Form Tags

Free-form tags such as mesh: fine or solver: default collapse under real workloads. They cannot be validated, cannot be compared numerically, and cannot drive automated regression checks. A schema imposes types, units, and required fields. The practical rule is: anything that changes the numerical result must be a typed, unit-annotated field; anything that only aids human interpretation (notes, analyst name, ticket ID) can remain a string.

A workable approach is a layered schema with a stable core and solver-specific extensions. The core captures quantities that exist in every CAE code (mesh size, element type, load magnitude, material stiffness, convergence tolerance). Extensions capture solver-specific keywords without polluting the core.

Core Schema Structure

The following JSON fragment illustrates a minimal but complete run record. It is a teaching example, not output from a specific solver run.

{
  "run_id": "2024-11-07T14:22:31Z_bracket_v3",
  "solver": { "name": "Abaqus", "version": "2023", "analysis_type": "static_general" },
  "mesh": {
    "element_family": "C3D10",
    "global_size_mm": 2.0,
    "local_refinement": [{ "region": "fillet_R5", "size_mm": 0.5 }],
    "node_count": 184320,
    "element_count": 112004,
    "quality": { "min_jacobian": 0.42, "max_aspect_ratio": 8.1 }
  },
  "boundary_conditions": [
    { "type": "encastre", "region": "face_A", "dof": [1,2,3,4,5,6] },
    { "type": "pressure", "region": "face_B", "magnitude_MPa": 12.5, "direction": "normal" }
  ],
  "materials": [
    { "name": "Al6061-T6", "model": "elastic_plastic",
      "E_MPa": 68900, "nu": 0.33, "yield_MPa": 276,
      "hardening": { "type": "isotropic", "table": [[276,0.0],[310,0.02]] } }
  ],
  "convergence": {
    "criterion": "force_residual",
    "tolerance": 0.005,
    "max_increments": 100,
    "initial_increment_s": 0.01,
    "min_increment_s": 1e-6
  }
}

Every numeric field carries its unit in the key name (_mm, _MPa, _s). This is not cosmetic: unit ambiguity is one of the most common causes of irreproducible CAE records. Storing units in the key avoids a separate units dictionary and makes the schema self-documenting.

Mesh Attributes: What Actually Matters

Mesh metadata should capture enough to reconstruct the discretization decision, not the full mesh file. The essential fields are element family (which encodes interpolation order and dimensionality), global target size, local refinement regions, and quality metrics. Node and element counts are useful for detecting accidental changes between runs.

Quality metrics deserve explicit thresholds. A minimum Jacobian below roughly 0.3 or an aspect ratio above 10 in a solid element is a common warning sign for poor convergence or inaccurate stress. Recording these values lets the registry flag runs that are numerically suspect before anyone inspects results.

Boundary Conditions and Loads

Boundary conditions must record the region identifier, the constrained degrees of freedom, and the magnitude with direction convention. The direction convention is critical: a pressure of 12.5 MPa applied "normal" to a face is unambiguous only if the face normal orientation is defined. The schema should therefore store either an explicit vector or a reference to a named coordinate system, and the same convention must be used in the report and any visualization.

For time-dependent loads, store the amplitude table reference rather than inlining large arrays. For example, "amplitude": "ramp_0_to_1_over_2s" with the table stored once at the experiment level.

Material Models

Material metadata is where schemas most often become solver-specific. A pragmatic pattern is a model discriminator plus a parameter block. Elastic models need E and nu; plastic models add a yield surface and hardening table; hyperelastic models need a strain-energy potential and its constants. The schema should require the model name and reject unknown parameters rather than silently accepting them.

For temperature-dependent properties, store the property as a table of (temperature, value) pairs and record the reference temperature. This prevents the common error of comparing runs that used different property evaluation temperatures.

Convergence Criteria

Convergence metadata determines whether two runs are comparable at all. Record the residual type (force, displacement, energy), the tolerance, the maximum number of increments or iterations, and the increment control parameters. A run that converged with a force residual tolerance of 0.005 is not equivalent to one that used 0.05, even if both report "converged."

The schema should also capture the achieved convergence, not just the requested tolerance. Storing the final residual and the number of increments used allows the registry to detect runs that barely converged and are therefore fragile.

Practical rule: If a field can change the numerical result, it must be typed and unit-annotated. If it cannot, keep it as a string and move on. Over-specifying the schema slows adoption; under-specifying it destroys reproducibility.

Schema Validation and Registry Integration

Once the schema is defined, validate every run record against it before ingestion. A JSON Schema or equivalent validator catches missing units, wrong types, and unknown material models at write time rather than at analysis time. The registry then indexes the typed fields, enabling queries such as "all runs with C3D10 elements, global size ≤ 2 mm, and force residual tolerance ≤ 0.005."

The diagram below shows how the five metadata groups flow from the analyst's input into the validated run record and then into registry-indexed fields.

Extending the Schema Without Breaking It

New solver versions and new material models will always appear. The safe extension pattern is additive: add optional fields under a namespaced extension block, never repurpose an existing field. For example, a new viscoelastic model becomes "model": "viscoelastic_pronyseries" with a prony parameter block, while existing elastic records remain valid. The registry should treat unknown extension blocks as opaque and index only the fields it understands.

Version the schema itself. Store schema_version in every record so that a future migration can identify which records need transformation. This is the difference between a metadata system that survives five years of solver upgrades and one that becomes an unqueryable archive.

Common failure: Recording only the requested convergence tolerance and not the achieved residual. A run that "converged" at 0.0049 against a 0.005 tolerance is technically valid but numerically fragile. Without the achieved value, the registry cannot distinguish it from a run that converged at 1e-6.

With the schema defined and validated, the next step is to connect it to the experiment tracking workflow so that every run is captured automatically rather than entered by hand. That integration is where the schema's value becomes visible: consistent, queryable, reproducible CAE records that support regression testing and model comparison across the entire project.