API Reference

MaterForge - Materials Formulation Engine with Python

A high-performance Python library for material property modeling and analysis. MaterForge provides comprehensive tools for defining, processing, and evaluating material properties as functions of temperature and other dependencies.

Key Features: - Temperature-dependent material property modeling - Multiple property definition formats (YAML-based) - Symbolic mathematics integration with SymPy - Piecewise function creation and evaluation - Material property visualization - Regression and data analysis capabilities - Integration with numerical simulation frameworks

Main Components: - Core: Material definitions and fundamental data structures - Parsing: YAML configuration parsing and property processing - Algorithms: Mathematical operations and property computations - Visualization: Property plotting and analysis tools - Data: Material databases and physical constants

class materforge.Material(name, properties=<factory>)

Bases: object

Generic material container with fully dynamic property tracking. All material properties are assigned dynamically via setattr and tracked automatically.

Parameters:

• name (str)

• properties (Dict[str, Basic])

name

Human-readable material identifier.

properties

Dictionary with all properties.

evaluate(symbol, value)

Evaluates all properties by substituting symbol=value.

Parameters:

• symbol (Symbol) – SymPy symbol to substitute (e.g. sp.Symbol(‘T’)).

• value – Value to substitute.

Return type:

Material

Returns:

New Material instance with name ‘{name}@{symbol}={value}’ and all properties substituted at the given value. Properties that fail evaluation are silently excluded.

Raises:

ValueError – If symbol is not sp.Symbol, or value is non-numeric.

name: str

properties: Dict[str, Basic]

property_names()

Returns all dynamically assigned property names.

Return type:

set

class materforge.PiecewiseBuilder

Bases: object

Centralised piecewise function creation with different build strategies.

static build_from_data(dep_array, prop_array, dependency, config, prop_name)

Builds a piecewise function from raw dependency-value arrays.

Handles ascending/descending input, optional pre-regression, and symbol substitution when the caller uses a non-placeholder symbol.

Parameters:

• dep_array (ndarray) – Dependency axis data.

• prop_array (ndarray) – Corresponding property values.

• dependency (Symbol) – SymPy symbol for the resulting expression.

• config (Dict) – Property configuration dict (bounds, regression).

• prop_name (str) – Property name used in log and error messages.

Return type:

Piecewise

Returns:

Symbolic piecewise function expressed in terms of dependency.

Raises:

ValueError – On null/empty/mismatched arrays or build failure.

static build_from_formulas(dep_points, equations, dependency, lower_bound_type='constant', upper_bound_type='constant')

Builds a piecewise function from symbolic equations and breakpoints.

Parameters:

• dep_points (ndarray) – Breakpoints defining segment boundaries (n+1 for n equations).

• equations (List[Union[str, Expr]]) – Symbolic expressions as strings or SymPy Expr objects.

• dependency (Symbol) – SymPy symbol used in the equations.

• lower_bound_type (str) – Boundary behaviour below dep_points[0].

• upper_bound_type (str) – Boundary behaviour above dep_points[-1].

Return type:

Piecewise

Returns:

Symbolic piecewise function.

Raises:

ValueError – On mismatched counts, invalid symbols, or parse failures.

class materforge.PiecewiseInverter(tolerance=1e-12)

Bases: object

Creates inverse functions for linear piecewise functions (degree <= 1 only).

Parameters:

tolerance (float)

static create_inverse(piecewise_func, input_symbol, output_symbol, tolerance=1e-12)

Creates the inverse of a linear piecewise function.

Parameters:

• piecewise_func (Union[Piecewise, Expr]) – Original piecewise function f(input_symbol).

• input_symbol (Union[Symbol, Basic]) – Independent variable of the original function.

• output_symbol (Union[Symbol, Basic]) – Symbol for the inverse function’s argument.

• tolerance (float) – Numerical tolerance for inversion stability.

Return type:

Piecewise

Returns:

Inverse piecewise function expressed in terms of output_symbol.

Raises:

ValueError – If any piece has degree > 1 or the function is non-monotonic.

Example

>>> dep = sp.Symbol("T")
>>> E   = sp.Symbol("E")
>>> pw  = sp.Piecewise((2*dep + 100, dep < 500), (3*dep - 400, True))
>>> inv = PiecewiseInverter.create_inverse(pw, dep, E)

class materforge.PropertyProcessor

Bases: PropertyProcessorBase

Orchestrates property processing by delegating to specialised handlers.

Properties are processed in PropertyType enum definition order, which guarantees CONSTANT_VALUE is resolved before any type that may reference those scalars (STEP_FUNCTION, TABULAR_DATA, etc.).

process_properties(material, dependency, properties, categorized_properties, base_dir, visualizer)

Processes all properties for the material.

Parameters:

• material (Material) – Target Material instance.

• dependency (Union[float, Symbol]) – SymPy symbol (symbolic mode) or float (numeric mode).

• properties (Dict[str, Any]) – Raw properties dict from the YAML config.

• categorized_properties (Dict[PropertyType, List[Tuple[str, Any]]]) – Properties pre-grouped by PropertyType.

• base_dir (Path) – Base directory for resolving relative file paths.

• visualizer – PropertyVisualizer instance, or None.

Return type:

None

class materforge.PropertyType(value)

Bases: Enum

An enumeration.

COMPUTED_PROPERTY = 6

CONSTANT_VALUE = 1

FILE_IMPORT = 3

INVALID = 7

PIECEWISE_EQUATION = 5

STEP_FUNCTION = 2

TABULAR_DATA = 4

class materforge.PropertyVisualizer(parser)

Bases: object

Handles visualization of material properties.

initialize_plots()

Initialises the figure and grid layout for all properties.

Return type:

None

is_visualization_enabled()

Returns True if visualization is active and a figure exists.

Return type:

bool

reset_visualization_tracking()

Clears the set of already-visualized properties.

Return type:

None

save_property_plots()

Saves the composed property figure to disk and closes it.

Return type:

None

static setup_style()

Applies global matplotlib style settings.

Return type:

None

visualize_property(material, prop_name, dependency, prop_type, x_data=None, y_data=None, has_regression=False, simplify_type=None, degree=1, segments=1, lower_bound=None, upper_bound=None, lower_bound_type='constant', upper_bound_type='constant')

Visualizes a single material property on the next available subplot.

Return type:

None

Parameters:

• material (Material)

• prop_name (str)

• dependency (float | Symbol)

• prop_type (str)

• x_data (ndarray | None)

• y_data (ndarray | None)

• has_regression (bool)

• simplify_type (str | None)

• degree (int)

• segments (int)

• lower_bound (float | None)

• upper_bound (float | None)

• lower_bound_type (str)

• upper_bound_type (str)

class materforge.SymbolRegistry

Bases: object

Registry for SymPy symbols to ensure uniqueness.

classmethod clear()

Clear all registered symbols.

Return type:

None

classmethod get(name)

Get or create a symbol with the given name.

Return type:

Symbol

Parameters:

name (str)

classmethod get_all()

Get all registered symbols.

Return type:

Dict[str, Symbol]

materforge.create_material(yaml_path, dependency, enable_plotting=True)

Creates a Material from a YAML configuration file.

Parameters:

• yaml_path (Union[str, Path]) – Path to the YAML configuration file.

• dependency (Symbol) – SymPy symbol used as the independent variable. YAML equations always use the placeholder ‘T’; it is substituted with this symbol at runtime.

• enable_plotting (bool) – Generate visualisation plots (default: True).

Return type:

Material

Returns:

Fully initialised Material instance.

Raises:

• FileNotFoundError – YAML file does not exist.

• TypeError – dependency is not a sp.Symbol.

• MaterialConfigError – YAML content is invalid or material creation fails.

• PropertyConfigError – A specific property block is structurally invalid.

Example

>>> material = create_material('steel.yaml', sp.Symbol('T'))
>>> material = create_material('copper.yaml', sp.Symbol('u_C'), enable_plotting=False)

materforge.ensure_ascending_order(dep_array, *value_arrays)

Ensures dep_array is in ascending order, flipping all arrays together if needed.

Parameters:

• dep_array (ndarray) – Dependency axis data.

• *value_arrays – Any number of paired value arrays to flip alongside dep_array.

Return type:

Tuple[ndarray, ...]

Returns:

Tuple of (dep_array, *value_arrays), all in ascending dep order.

Raises:

ValueError – If the array is neither strictly ascending nor strictly descending.

materforge.evaluate_material_properties(material, symbol, value)

Evaluates all symbolic properties at a given numeric value.

Parameters:

• material (Material) – A fully processed Material instance.

• symbol (Symbol) – SymPy symbol to substitute.

• value – Numeric value to substitute.

Return type:

Material

Returns:

New Material with all properties evaluated to numeric values.

Raises:

TypeError – If material is not a Material instance.

Example

>>> evaluate_material_properties(material, T, 500.0)

materforge.get_material_info(yaml_path)

Extracts material metadata from a YAML file without full processing.

Parameters:

yaml_path (Union[str, Path]) – Path to the YAML configuration file.

Returns:

name, properties, total_properties, property_types, and any additional top-level YAML fields.

Return type:

Dict with keys

Raises:

• FileNotFoundError – File does not exist.

• PropertyConfigError – A specific property block is structurally invalid.

• MaterialConfigError – Content is invalid or a required field is missing.

Example

>>> info = get_material_info('steel.yaml')
>>> print(info['name'], info['total_properties'])

materforge.get_material_path(name)

Returns the path to a bundled material’s YAML file.

Matching is case-insensitive. Useful when you want to read or copy the YAML rather than load it directly.

Parameters:

name (str) – Name of a bundled material (see list_materials()).

Return type:

Path

Returns:

Filesystem path to the material’s YAML file.

Raises:

ValueError – If name does not match a bundled material; the message lists the available names.

materforge.get_material_property_names(material)

Returns all property names dynamically assigned to a material instance.

Parameters:

material (Material) – A fully processed Material instance.

Return type:

Set[str]

Returns:

Property names assigned during processing.

Raises:

TypeError – Argument is not a Material instance.

Example

>>> material = create_material('steel.yaml', sp.Symbol('T'))
>>> print(get_material_property_names(material))

materforge.interpolate_value(dep_value, dep_array, prop_array, lower_bound_type, upper_bound_type)

Interpolates a property value at dep_value using the provided data arrays.

Parameters:

• dep_value – Dependency value at which to interpolate.

• dep_array (ndarray) – Dependency axis data (must be sorted ascending).

• prop_array (ndarray) – Corresponding property values.

• lower_bound_type (str) – Behaviour below dep_array[0]: CONSTANT_KEY or LINEAR_KEY.

• upper_bound_type (str) – Behaviour above dep_array[-1]: CONSTANT_KEY or LINEAR_KEY.

Returns:

Interpolated value.

Raises:

ValueError – If dep_value is non-finite, arrays are empty or mismatched, or extrapolation is requested on a degenerate interval.

materforge.list_materials()

Returns the names of the bundled example materials, sorted alphabetically.

Return type:

List[str]

materforge.load_material(name, dependency, enable_plotting=False)

Loads a bundled example material by name.

A thin wrapper around materforge.create_material() for the YAML files shipped with the package. Plotting is off by default so loading an example never writes plot files next to the installed package.

Parameters:

• name (str) – Name of a bundled material (see list_materials()).

• dependency (Symbol) – SymPy symbol used as the independent variable, exactly as in materforge.create_material().

• enable_plotting (bool) – Generate visualisation plots (default: False).

Return type:

Material

Returns:

Fully initialised Material instance.

Raises:

• ValueError – If name does not match a bundled material.

• TypeError – If dependency is not a sympy Symbol.

Example

>>> import sympy as sp
>>> from materforge import load_material
>>> steel = load_material('1.4301', sp.Symbol('T'))

materforge.validate_yaml_file(yaml_path)

Validates a YAML file without creating the material.

Parameters:

yaml_path (Union[str, Path]) – Path to the YAML configuration file to validate.

Return type:

bool

Returns:

True if the file is structurally valid.

Raises:

• FileNotFoundError – File does not exist.

• PropertyConfigError – A specific property block is structurally invalid.

• MaterialConfigError – Top-level YAML content is invalid.

Example

>>> is_valid = validate_yaml_file('steel.yaml')

Core Module

Core data structures and material definitions.

This module contains the fundamental classes and interfaces that define materials, and the core abstractions used throughout the MaterForge library.

class materforge.core.Material(name, properties=<factory>)

Bases: object

Generic material container with fully dynamic property tracking. All material properties are assigned dynamically via setattr and tracked automatically.

Parameters:

• name (str)

• properties (Dict[str, Basic])

name

Human-readable material identifier.

properties

Dictionary with all properties.

evaluate(symbol, value)

Evaluates all properties by substituting symbol=value.

Parameters:

• symbol (Symbol) – SymPy symbol to substitute (e.g. sp.Symbol(‘T’)).

• value – Value to substitute.

Return type:

Material

Returns:

New Material instance with name ‘{name}@{symbol}={value}’ and all properties substituted at the given value. Properties that fail evaluation are silently excluded.

Raises:

ValueError – If symbol is not sp.Symbol, or value is non-numeric.

name: str

properties: Dict[str, Basic]

property_names()

Returns all dynamically assigned property names.

Return type:

set

class materforge.core.SymbolRegistry

Bases: object

Registry for SymPy symbols to ensure uniqueness.

classmethod clear()

Clear all registered symbols.

Return type:

None

classmethod get(name)

Get or create a symbol with the given name.

Return type:

Symbol

Parameters:

name (str)

classmethod get_all()

Get all registered symbols.

Return type:

Dict[str, Symbol]

Material Class

class materforge.Material(name, properties=<factory>)

Bases: object

Generic material container with fully dynamic property tracking. All material properties are assigned dynamically via setattr and tracked automatically.

Parameters:

• name (str)

• properties (Dict[str, Basic])

name

Human-readable material identifier.

properties

Dictionary with all properties.

evaluate(symbol, value)

Evaluates all properties by substituting symbol=value.

Parameters:

• symbol (Symbol) – SymPy symbol to substitute (e.g. sp.Symbol(‘T’)).

• value – Value to substitute.

Return type:

Material

Returns:

New Material instance with name ‘{name}@{symbol}={value}’ and all properties substituted at the given value. Properties that fail evaluation are silently excluded.

Raises:

ValueError – If symbol is not sp.Symbol, or value is non-numeric.

name: str

properties: Dict[str, Basic]

property_names()

Returns all dynamically assigned property names.

Return type:

set

Bundled Materials

Helpers for the reference materials shipped with the package. See Load Bundled Example Materials for usage.

materforge.list_materials()

Returns the names of the bundled example materials, sorted alphabetically.

Return type:

List[str]

materforge.load_material(name, dependency, enable_plotting=False)

Loads a bundled example material by name.

A thin wrapper around materforge.create_material() for the YAML files shipped with the package. Plotting is off by default so loading an example never writes plot files next to the installed package.

Parameters:

• name (str) – Name of a bundled material (see list_materials()).

• dependency (Symbol) – SymPy symbol used as the independent variable, exactly as in materforge.create_material().

• enable_plotting (bool) – Generate visualisation plots (default: False).

Return type:

Material

Returns:

Fully initialised Material instance.

Raises:

• ValueError – If name does not match a bundled material.

• TypeError – If dependency is not a sympy Symbol.

Example

>>> import sympy as sp
>>> from materforge import load_material
>>> steel = load_material('1.4301', sp.Symbol('T'))

materforge.get_material_path(name)

Returns the path to a bundled material’s YAML file.

Matching is case-insensitive. Useful when you want to read or copy the YAML rather than load it directly.

Parameters:

name (str) – Name of a bundled material (see list_materials()).

Return type:

Path

Returns:

Filesystem path to the material’s YAML file.

Raises:

ValueError – If name does not match a bundled material; the message lists the available names.

Command-Line Interface

The materforge command wraps the public API for use from a shell. See the Use the Command-Line Interface guide for the subcommands and examples.

materforge.cli.main(argv=None)

Runs the MaterForge CLI and returns a process exit code.

Parameters:

argv (Optional[Sequence[str]]) – Argument list to parse (defaults to sys.argv[1:]).

Return type:

int

Returns:

0 on success, 1 on a handled error.

materforge.cli.validate_entry(argv=None)

Console-script shim for the legacy materforge-validate command.

Forwards its arguments to materforge validate so the standalone entry point keeps working alongside the unified CLI.

Return type:

int

Parameters:

argv (Sequence[str] | None)

Algorithms Module

Core computational algorithms for materials property processing.

This module provides mathematical algorithms for processing material properties, including interpolation, regression, piecewise function construction, and property inversion operations.

class materforge.algorithms.PiecewiseBuilder

Bases: object

Centralised piecewise function creation with different build strategies.

static build_from_data(dep_array, prop_array, dependency, config, prop_name)

Builds a piecewise function from raw dependency-value arrays.

Handles ascending/descending input, optional pre-regression, and symbol substitution when the caller uses a non-placeholder symbol.

Parameters:

• dep_array (ndarray) – Dependency axis data.

• prop_array (ndarray) – Corresponding property values.

• dependency (Symbol) – SymPy symbol for the resulting expression.

• config (Dict) – Property configuration dict (bounds, regression).

• prop_name (str) – Property name used in log and error messages.

Return type:

Piecewise

Returns:

Symbolic piecewise function expressed in terms of dependency.

Raises:

ValueError – On null/empty/mismatched arrays or build failure.

static build_from_formulas(dep_points, equations, dependency, lower_bound_type='constant', upper_bound_type='constant')

Builds a piecewise function from symbolic equations and breakpoints.

Parameters:

• dep_points (ndarray) – Breakpoints defining segment boundaries (n+1 for n equations).

• equations (List[Union[str, Expr]]) – Symbolic expressions as strings or SymPy Expr objects.

• dependency (Symbol) – SymPy symbol used in the equations.

• lower_bound_type (str) – Boundary behaviour below dep_points[0].

• upper_bound_type (str) – Boundary behaviour above dep_points[-1].

Return type:

Piecewise

Returns:

Symbolic piecewise function.

Raises:

ValueError – On mismatched counts, invalid symbols, or parse failures.

class materforge.algorithms.PiecewiseInverter(tolerance=1e-12)

Bases: object

Creates inverse functions for linear piecewise functions (degree <= 1 only).

Parameters:

tolerance (float)

static create_inverse(piecewise_func, input_symbol, output_symbol, tolerance=1e-12)

Creates the inverse of a linear piecewise function.

Parameters:

• piecewise_func (Union[Piecewise, Expr]) – Original piecewise function f(input_symbol).

• input_symbol (Union[Symbol, Basic]) – Independent variable of the original function.

• output_symbol (Union[Symbol, Basic]) – Symbol for the inverse function’s argument.

• tolerance (float) – Numerical tolerance for inversion stability.

Return type:

Piecewise

Returns:

Inverse piecewise function expressed in terms of output_symbol.

Raises:

ValueError – If any piece has degree > 1 or the function is non-monotonic.

Example

>>> dep = sp.Symbol("T")
>>> E   = sp.Symbol("E")
>>> pw  = sp.Piecewise((2*dep + 100, dep < 500), (3*dep - 400, True))
>>> inv = PiecewiseInverter.create_inverse(pw, dep, E)

class materforge.algorithms.RegressionProcessor

Bases: object

Handles all regression-related functionality.

static get_symbolic_conditions(pwlf_, dependency, lower_, upper_)

Builds SymPy (expression, condition) pairs from a fitted PWLF model.

Parameters:

• pwlf – Fitted PiecewiseLinFit instance.

• dependency (Symbol) – SymPy symbol used in the expressions.

• lower – Lower boundary type (CONSTANT_KEY or LINEAR_KEY).

• upper – Upper boundary type (CONSTANT_KEY or LINEAR_KEY).

• pwlf_ (PiecewiseLinFit)

• lower_ (str)

• upper_ (str)

Return type:

List[Tuple]

Returns:

List of (expr, condition) tuples suitable for sp.Piecewise.

static get_symbolic_eqn(pwlf_, segment_number, dependency)

Constructs the symbolic polynomial equation for a single PWLF segment.

Parameters:

• pwlf – Fitted PiecewiseLinFit instance.

• segment_number (int) – 1-based segment index.

• dependency (Union[float, Symbol]) – SymPy symbol or numeric value.

• pwlf_ (PiecewiseLinFit)

Return type:

Expr

Returns:

SymPy expression for the segment.

Raises:

ValueError – On invalid degree or out-of-range segment number.

static process_regression(dep_array, prop_array, dependency, lower_bound_type, upper_bound_type, degree, segments, seed=13579)

Fits a piecewise polynomial regression and returns a SymPy Piecewise.

Parameters:

• dep_array – Dependency axis data.

• prop_array – Corresponding property values.

• dependency (Symbol) – SymPy symbol for the resulting expression.

• lower_bound_type (str) – Boundary behaviour below dep_array[0].

• upper_bound_type (str) – Boundary behaviour above dep_array[-1].

• degree (int) – Polynomial degree per segment.

• segments (int) – Number of piecewise segments.

• seed (int) – Random seed for PWLF optimisation.

Return type:

Piecewise

Returns:

Symbolic piecewise function expressed in terms of dependency.

Raises:

ValueError – If PWLF fitting fails.

static process_regression_params(prop_config, prop_name, data_length)

Extracts and validates regression parameters from a property config dict.

Parameters:

• prop_config (dict) – Full property configuration dictionary.

• prop_name (str) – Property name used in log and error messages.

• data_length (int) – Number of data points (used to validate segment count).

Return type:

Tuple[bool, Optional[str], Optional[int], Optional[int]]

Returns:

Tuple of (has_regression, simplify_type, degree, segments). All values are None when has_regression is False.

Raises:

ValueError – On invalid or missing regression parameters.

materforge.algorithms.ensure_ascending_order(dep_array, *value_arrays)

Ensures dep_array is in ascending order, flipping all arrays together if needed.

Parameters:

• dep_array (ndarray) – Dependency axis data.

• *value_arrays – Any number of paired value arrays to flip alongside dep_array.

Return type:

Tuple[ndarray, ...]

Returns:

Tuple of (dep_array, *value_arrays), all in ascending dep order.

Raises:

ValueError – If the array is neither strictly ascending nor strictly descending.

materforge.algorithms.interpolate_value(dep_value, dep_array, prop_array, lower_bound_type, upper_bound_type)

Interpolates a property value at dep_value using the provided data arrays.

Parameters:

• dep_value – Dependency value at which to interpolate.

• dep_array (ndarray) – Dependency axis data (must be sorted ascending).

• prop_array (ndarray) – Corresponding property values.

• lower_bound_type (str) – Behaviour below dep_array[0]: CONSTANT_KEY or LINEAR_KEY.

• upper_bound_type (str) – Behaviour above dep_array[-1]: CONSTANT_KEY or LINEAR_KEY.

Returns:

Interpolated value.

Raises:

ValueError – If dep_value is non-finite, arrays are empty or mismatched, or extrapolation is requested on a degenerate interval.

Parsing Module

Parsing and configuration modules for MaterForge.

This package handles YAML parsing, property type detection, validation, and material creation from configuration files.

class materforge.parsing.MaterialYAMLParser(yaml_path)

Bases: YAMLFileParser

Parser for material YAML configuration files.

Validates and processes a schema-agnostic YAML file containing a name and a properties block. All thermophysical properties live in the properties block and are assigned dynamically to the Material instance.

Parameters:

yaml_path (str | Path)

create_material(dependency, enable_plotting=True)

Creates a Material instance from the parsed configuration.

Parameters:

• dependency (Symbol) – SymPy symbol used as the independent variable in property expressions (e.g. sp.Symbol(‘T’)).

• enable_plotting (bool) – Whether to generate and save property plots.

Return type:

Material

Returns:

Fully initialised Material with all properties assigned.

Raises:

MaterialConfigError – If configuration is invalid or property processing fails.

class materforge.parsing.PropertyProcessor

Bases: PropertyProcessorBase

Orchestrates property processing by delegating to specialised handlers.

Properties are processed in PropertyType enum definition order, which guarantees CONSTANT_VALUE is resolved before any type that may reference those scalars (STEP_FUNCTION, TABULAR_DATA, etc.).

process_properties(material, dependency, properties, categorized_properties, base_dir, visualizer)

Processes all properties for the material.

Parameters:

• material (Material) – Target Material instance.

• dependency (Union[float, Symbol]) – SymPy symbol (symbolic mode) or float (numeric mode).

• properties (Dict[str, Any]) – Raw properties dict from the YAML config.

• categorized_properties (Dict[PropertyType, List[Tuple[str, Any]]]) – Properties pre-grouped by PropertyType.

• base_dir (Path) – Base directory for resolving relative file paths.

• visualizer – PropertyVisualizer instance, or None.

Return type:

None

class materforge.parsing.PropertyType(value)

Bases: Enum

An enumeration.

COMPUTED_PROPERTY = 6

CONSTANT_VALUE = 1

FILE_IMPORT = 3

INVALID = 7

PIECEWISE_EQUATION = 5

STEP_FUNCTION = 2

TABULAR_DATA = 4

class materforge.parsing.PropertyTypeDetector

Bases: object

Detects and validates property types from YAML config values.

DETECTION_RULES = [(<function PropertyTypeDetector.<lambda>>, PropertyType.FILE_IMPORT), (<function PropertyTypeDetector.<lambda>>, PropertyType.STEP_FUNCTION), (<function PropertyTypeDetector.<lambda>>, PropertyType.TABULAR_DATA), (<function PropertyTypeDetector.<lambda>>, PropertyType.PIECEWISE_EQUATION), (<function PropertyTypeDetector.<lambda>>, PropertyType.COMPUTED_PROPERTY)]

static determine_property_type(prop_name, config)

Determines the PropertyType for a config entry using rule-based detection.

Parameters:

• prop_name (str) – Name of the property (used in error messages only).

• config (Any) – Raw config value from the YAML properties block.

Return type:

PropertyType

Returns:

The detected PropertyType.

Raises:

ValueError – If config is not numeric, not a dict, or matches no rule.

static validate_property_config(prop_name, config, prop_type)

Performs strict structural validation for the detected property type.

Parameters:

• prop_name (str) – Name of the property.

• config (Any) – Raw config value from the YAML properties block.

• prop_type (PropertyType) – The already-detected PropertyType.

Raises:

• ValueError – If config structure is invalid for the given type.

• NotImplementedError – If no validator exists for prop_type.

Return type:

None

materforge.parsing.create_material(yaml_path, dependency, enable_plotting=True)

Creates a Material from a YAML configuration file.

Parameters:

• yaml_path (Union[str, Path]) – Path to the YAML configuration file.

• dependency (Symbol) – SymPy symbol used as the independent variable. YAML equations always use the placeholder ‘T’; it is substituted with this symbol at runtime.

• enable_plotting (bool) – Generate visualisation plots (default: True).

Return type:

Material

Returns:

Fully initialised Material instance.

Raises:

• FileNotFoundError – YAML file does not exist.

• TypeError – dependency is not a sp.Symbol.

• MaterialConfigError – YAML content is invalid or material creation fails.

• PropertyConfigError – A specific property block is structurally invalid.

Example

>>> material = create_material('steel.yaml', sp.Symbol('T'))
>>> material = create_material('copper.yaml', sp.Symbol('u_C'), enable_plotting=False)

materforge.parsing.evaluate_material_properties(material, symbol, value)

Evaluates all symbolic properties at a given numeric value.

Parameters:

• material (Material) – A fully processed Material instance.

• symbol (Symbol) – SymPy symbol to substitute.

• value – Numeric value to substitute.

Return type:

Material

Returns:

New Material with all properties evaluated to numeric values.

Raises:

TypeError – If material is not a Material instance.

Example

>>> evaluate_material_properties(material, T, 500.0)

materforge.parsing.get_material_info(yaml_path)

Extracts material metadata from a YAML file without full processing.

Parameters:

yaml_path (Union[str, Path]) – Path to the YAML configuration file.

Returns:

name, properties, total_properties, property_types, and any additional top-level YAML fields.

Return type:

Dict with keys

Raises:

• FileNotFoundError – File does not exist.

• PropertyConfigError – A specific property block is structurally invalid.

• MaterialConfigError – Content is invalid or a required field is missing.

Example

>>> info = get_material_info('steel.yaml')
>>> print(info['name'], info['total_properties'])

materforge.parsing.get_material_property_names(material)

Returns all property names dynamically assigned to a material instance.

Parameters:

material (Material) – A fully processed Material instance.

Return type:

Set[str]

Returns:

Property names assigned during processing.

Raises:

TypeError – Argument is not a Material instance.

Example

>>> material = create_material('steel.yaml', sp.Symbol('T'))
>>> print(get_material_property_names(material))

materforge.parsing.validate_yaml_file(yaml_path)

Validates a YAML file without creating the material.

Parameters:

yaml_path (Union[str, Path]) – Path to the YAML configuration file to validate.

Return type:

bool

Returns:

True if the file is structurally valid.

Raises:

• FileNotFoundError – File does not exist.

• PropertyConfigError – A specific property block is structurally invalid.

• MaterialConfigError – Top-level YAML content is invalid.

Example

>>> is_valid = validate_yaml_file('steel.yaml')

Visualization Module

Visualization tools for material properties.

class materforge.visualization.PropertyVisualizer(parser)

Bases: object

Handles visualization of material properties.

initialize_plots()

Initialises the figure and grid layout for all properties.

Return type:

None

is_visualization_enabled()

Returns True if visualization is active and a figure exists.

Return type:

bool

reset_visualization_tracking()

Clears the set of already-visualized properties.

Return type:

None

save_property_plots()

Saves the composed property figure to disk and closes it.

Return type:

None

static setup_style()

Applies global matplotlib style settings.

Return type:

None

visualize_property(material, prop_name, dependency, prop_type, x_data=None, y_data=None, has_regression=False, simplify_type=None, degree=1, segments=1, lower_bound=None, upper_bound=None, lower_bound_type='constant', upper_bound_type='constant')

Visualizes a single material property on the next available subplot.

Return type:

None

Parameters:

• material (Material)

• prop_name (str)

• dependency (float | Symbol)

• prop_type (str)

• x_data (ndarray | None)

• y_data (ndarray | None)

• has_regression (bool)

• simplify_type (str | None)

• degree (int)

• segments (int)

• lower_bound (float | None)

• upper_bound (float | None)

• lower_bound_type (str)

• upper_bound_type (str)