YAML Schema for Material Definition

This document defines the schema for material definition YAML files in MaterForge.

Schema Overview

A valid material definition requires exactly two top-level fields:

name: "myMaterial"   # string identifier - required
properties:          # map of property definitions - required
  ...

No other top-level fields are required. Any property name is valid inside properties. The schema is fully driven by what you put there - no hardcoded material types, compositions, or required property names.

Property Definition Types

1. Constant Value

A single numeric value. Not dependency-driven.

properties:
    density: 7000.0
    thermal_expansion_coefficient: 16.3e-6

Note: Scientific notations are also supported (1.71401e5).

2. Step Function

A property that changes discontinuously at a single transition point. dependency must be a scalar property reference or arithmetic expression.

properties:
    solidus_temp: 1605.

    latent_heat_of_fusion:
        dependency: solidus_temp + 5
        value: [0.0, 171401.0]   # [before_transition, after_transition]
        bounds: [constant, constant]

3. File Import

Data loaded from an external file. Relative paths are resolved from the YAML file location.

properties:
    # Excel
    heat_capacity:
        file_path: ./material_data.xlsx
        dependency_column: T (K)
        property_column: Specific heat (J/(Kg K))
        bounds: [constant, constant]

    # CSV
    density:
        file_path: ./density.csv
        dependency_column: Temperature
        property_column: Density
        bounds: [constant, constant]

    # Text file - headerless, use column index
    thermal_conductivity:
        file_path: ./conductivity.txt
        dependency_column: 0
        property_column: 1
        bounds: [constant, constant]

Supported formats: .xlsx, .csv, .txt (space/tab separated).

4. Tabular Data

Explicit paired dependency-value lists. Both lists must have the same length.

properties:
    heat_conductivity:
        dependency: [500, 1000, 1600, 1700, 1750, 2000, 2500]
        value: [19.25, 25.47, 32.94, 33.52, 31.53, 35.33, 42.95]
        bounds: [constant, constant]

    # Scalar property references in dependency
    latent_heat_of_fusion:
        dependency: [solidus_temp - 1, liquidus_temp + 1]
        value: [0.0, 171401.0]
        bounds: [constant, constant]

    # Tuple (start, increment) - length inferred from value list
    heat_capacity:
        dependency: (273.15, 100.0)
        value: [897, 921, 950, 980, 1010, 1040, 1070, 1084]
        bounds: [constant, constant]

    # Tuple with negative increment
    density:
        dependency: (1735.0, -5)
        value: [7037.47, 7060.15, 7088.80, 7110.46, 7127.68]
        bounds: [constant, constant]

5. Piecewise Equation

n breakpoints in dependency define n-1 equations.

properties:
    viscosity:
        dependency: [300, 1660, 1736, 3000]
        equation: [7877.39-0.37*T, 11816.63-2.74*T, 8596.40-0.88*T]
        bounds: [constant, constant]

T in equations is a placeholder only. MaterForge substitutes it with the symbol passed to create_material(..., dependency=symbol) at runtime. The final symbolic expressions use your symbol, not T.

6. Computed Property

Derived from other properties using a symbolic expression. MaterForge resolves processing order automatically via topological sort - no manual ordering needed.

properties:
    thermal_diffusivity:
        dependency: (3000, 300, -5.0)
        equation: heat_conductivity / (density * heat_capacity)
        bounds: [linear, linear]
        regression:
            simplify: post
            degree: 2
            segments: 3

    energy_density:
        dependency: (300, 3000, 5.0)
        equation: density * specific_enthalpy
        bounds: [linear, linear]

Dependency Definition Formats

# 1. Explicit list
dependency: [300, 500, 800, 1000]

# 2. Tuple (start, increment) - length inferred from value list
dependency: (300, 50)

# 3. Tuple (start, stop, step) - step is float
dependency: (300, 1000, 10.0)     # 300, 310, ..., 1000

# 4. Tuple (start, stop, points) - points is integer
dependency: (300, 1000, 71)       # 71 evenly spaced values

# 5. Decreasing range
dependency: (1000, 300, -5.0)     # 1000, 995, ..., 300

Scalar references and arithmetic are valid inside lists:

dependency: [solidus_temp - 1, liquidus_temp + 1]
dependency: solidus_temp + 5      # single reference for step functions

Bounds Options

Required for all non-constant property types.

bounds: [lower_bound, upper_bound]

Option

Behaviour

constant

Clamp to the boundary value outside the range

linear

Linear extrapolation beyond the range

Regression Configuration

Optional. Reduces expression complexity and smooths noisy input data.

regression:
    simplify: pre    # 'pre': on raw data before symbolic processing
                     # 'post': after symbolic expressions are evaluated
    degree: 1        # polynomial degree per segment (1=linear, 2=quadratic, ...)
    segments: 3      # number of piecewise segments (<=8 recommended)

Note: segments > 6 risk overfitting - MaterForge logs a warning. Use degree: 1 for any property you intend to invert with PiecewiseInverter.

Visualization

Plots are generated automatically when dependency is a SymPy symbol:

import sympy as sp
from materforge.parsing.api import create_material

T = sp.Symbol('T')   # any symbol - not limited to temperature
mat = create_material('myAlloy.yaml', dependency=T, enable_plotting=True)
# Plots saved automatically

Property Inversion

For any piecewise-linear property, create its inverse with PiecewiseInverter:

from materforge.algorithms.piecewise_inverter import PiecewiseInverter

T = sp.Symbol('T')
E = sp.Symbol('E')

mat = create_material('myAlloy.yaml', dependency=T)
inverse = PiecewiseInverter.create_inverse(mat.energy_density, 'T', 'E')

# Given a property value, recover the dependency value
recovered = float(inverse.subs(E, 1.5e9))

Limitation: linear piecewise only (degree: 1). Higher-degree segments are not supported.

Validation Rules

  1. name and properties are the only required top-level fields

  2. A property cannot be defined more than once

  3. All dependencies of a computed property must be defined in the same properties block

  4. Dependency arrays must be monotonic for interpolation

  5. For tabular data, dependency and value lists must have equal length

  6. File paths must exist and be readable; columns must match exactly

  7. Tuple increment must be non-zero

  8. bounds is required for all non-constant property types

  9. Regression segments must be a positive integer

Important Notes

  • All numeric values must use . as decimal separator, not ,

  • Interpolation between data points is automatic for tabular and file-import properties

  • Property processing order is resolved automatically - position in the file does not matter

  • The T placeholder in equations carries no special meaning; it is substituted at runtime