Design Philosophy of MaterForge

This document explains the core design principles, architectural decisions, and the rationale behind MaterForge’s structure and implementation.

Core Principles

MaterForge is built upon several core principles:

  • Modularity: Clearly separated components for ease of maintenance, testing, and extensibility

  • Flexibility: Any material kind, any property name, any dependency variable - the YAML schema drives everything with no hardcoded constraints

  • Performance: Leverage symbolic computation for high-performance simulations

  • Transparency and Reproducibility: Clearly document material property definitions and computations to ensure reproducibility

Layered Architecture

MaterForge follows a layered architecture to separate concerns clearly:

1. User Interface Layer (YAML Configuration)

  • Provides a simple, human-readable format for defining any material and its properties

  • Allows users to specify properties using multiple intuitive methods (constants, step functions, interpolation points, file-based data, piecewise equations, computed properties)

  • Schema-agnostic: no required fields beyond name and properties

  • Ensures clarity, readability, and ease of use

2. Parsing Layer (Python)

  • Configuration Processing: Handles YAML parsing and validation through MaterialYAMLParser

  • Property Type Detection: Automatically determines property definition types using PropertyTypeDetector

  • Dependency Resolution: Processes various dependency definition formats via DependencyResolver

  • Data Handling: Manages file I/O for external data sources through load_property_data

3. Symbolic Representation Layer (SymPy)

  • Uses symbolic mathematics (via SymPy) internally to represent material properties

  • The dependency symbol is supplied at runtime via create_material(..., dependency=symbol) - any SymPy symbol is valid (temperature, pressure, composition fraction, strain, etc.)

  • Equations in YAML files use T as a placeholder; MaterForge substitutes it with the caller-supplied symbol automatically

  • Enables symbolic manipulation, simplification, and validation of property definitions

  • Facilitates automatic computation of derived properties through symbolic expressions

4. Algorithms Layer (Python)

  • Interpolation: Robust interpolation methods for evaluating dependency-driven properties

  • Regression: Data simplification and piecewise function generation via RegressionProcessor

  • Piecewise Functions: Creating piecewise expressions through PiecewiseBuilder

  • Inversion: Creating inverse functions for specialized applications

5. Visualization Layer (Python)

  • Automatic plot generation for material properties through PropertyVisualizer

  • Property visualization and validation

  • Integration with matplotlib for scientific plotting

6. Core Layer (Python)

  • Material: Schema-agnostic material container with fully dynamic property tracking

  • Interfaces: Abstract base classes for extensibility

Modular Architecture

MaterForge’s architecture is organized into distinct modules:

Core Module (materforge.core)

  • Material: Schema-agnostic material container - properties are assigned dynamically via setattr and tracked automatically; no material type or composition required

  • Interfaces: Abstract base classes for extensibility (PropertyProcessor, DependencyResolver, etc.)

Parsing Module (materforge.parsing)

  • API: Main entry points (create_material, validate_yaml_file, get_material_info)

  • Configuration: YAML parsing and validation through MaterialYAMLParser

  • Processors: Property and dependency processing (PropertyProcessor, DependencyResolver)

  • I/O: File handling for external data (load_property_data)

  • Validation: Type detection and error handling (PropertyTypeDetector)

Algorithms Module (materforge.algorithms)

  • Interpolation: Dependency-driven property evaluation

  • Regression: Data simplification and fitting through RegressionProcessor

  • Piecewise: Piecewise function construction via PiecewiseBuilder

  • Inversion: Inverse function creation for specialized applications

Visualization Module (materforge.visualization)

  • Property Plots: Automatic visualization generation through PropertyVisualizer

  • Scientific Plotting: Integration with matplotlib for high-quality plots

Data Module (materforge.data)

  • Materials: Example material configurations (Steel 1.4301, Aluminum, etc.)

Why YAML?

YAML was chosen as the primary configuration format because:

  • Human-readable: Easy to edit manually and understand

  • Structured: Naturally supports nested structures required by complex material definitions

  • Ecosystem Integration: Seamless integration with Python via ruamel.yaml

  • Reference Support: Allows referencing previously defined scalar properties within the file (e.g., solidus_temp, liquidus_temp)

  • Version Control Friendly: Text-based format works well with git and other VCS

Integration with pystencils

MaterForge integrates with pystencils through the following workflow:

  1. Symbolic Definition: Material properties are defined symbolically in MaterForge using YAML configurations

  2. Property Processing: The parsing system converts YAML definitions into SymPy expressions

  3. Symbolic Evaluation: Material properties can be evaluated at specific dependency values or kept as symbolic expressions for direct use in simulations

  4. Simulation Integration: Symbolic expressions can be used directly in pystencils-based simulations

This integration allows MaterForge to leverage:

  • Symbolic mathematics from SymPy for property relationships

  • Dependency-driven material properties in numerical simulations

  • Flexible property definitions that adapt to simulation needs

Property Type System

MaterForge uses a property type detection system with six distinct types:

Six Property Types

  1. CONSTANT_VALUE: Simple numeric values for dependency-independent properties

  2. STEP_FUNCTION: Discontinuous changes at a scalar transition point

  3. FILE_IMPORT: Data loaded from external files (Excel, CSV, text)

  4. TABULAR_DATA: Explicit dependency-property value pairs

  5. PIECEWISE_EQUATION: Multiple equations for different dependency variable ranges

  6. COMPUTED_PROPERTY: Properties calculated from other already-defined properties

Automatic Type Detection

The PropertyTypeDetector automatically detects property types based on configuration structure:

  • Rule-based detection with priority ordering

  • Comprehensive validation for each type

  • Clear error messages for invalid configurations

Dependency Resolution

MaterForge automatically handles property dependencies:

Dependency Analysis

  • Extracts dependencies from symbolic expressions using SymPy

  • Validates that all required properties are available

  • Detects and prevents circular dependencies through graph analysis

Processing Order

  • Automatically determines correct processing order using topological sorting

  • Processes dependencies before dependent properties

  • Handles complex dependency chains transparently

Schema-Agnostic Material Model

The Material class imposes no structural constraints:

  • Any property name is valid - density, viscosity, band_gap, yield_strength, etc.

  • All properties are assigned dynamically and tracked automatically

  • No material type, composition, or element list required

  • The YAML schema drives everything; the Python class is a generic container

Error Handling Philosophy

MaterForge emphasizes clear, actionable error messages:

Validation at Every Layer

  • YAML syntax and structure validation

  • Property configuration validation through PropertyTypeDetector

  • Data quality validation in file processing

  • Dependency validation with circular dependency detection

Contextual Error Messages

  • Specific error locations and suggestions for fixes

  • Clear explanation of what went wrong and how to fix it

  • Symbol mismatch detection: if the wrong dependency symbol is passed to evaluate(), the error reports exactly which symbol the expression requires

Performance Optimization

Symbolic Computation

  • Efficient SymPy expression handling

  • Optimized property evaluation via Material.evaluate(symbol, value)

  • Minimal symbolic overhead for numeric evaluations

Memory Efficiency

  • Efficient data structures for large datasets

  • Optional regression for memory reduction and expression simplification

  • Streaming processing for large files

Testing and Validation

Unit Testing

  • Individual component testing for all modules

  • Property type validation testing

  • Algorithm correctness verification

Integration Testing

  • End-to-end workflow testing

  • File format compatibility testing

  • Property dependency resolution testing

Scientific Computing Integration

SymPy Integration

  • Properties as SymPy expressions enable symbolic manipulation

  • Any SymPy symbol can serve as the dependency variable

  • Mathematical expression validation and simplification

NumPy Integration

  • Efficient array processing for dependency variable and property data

  • Vectorized operations for performance

  • Seamless conversion between symbolic and numeric representations

Matplotlib Integration

  • Automatic plot generation for property visualization

  • Publication-quality scientific plots

  • Customizable visualization options

This design philosophy ensures MaterForge is both powerful and user-friendly, suitable for research applications while maintaining the flexibility needed for diverse materials science applications - from classical metals and alloys to polymers, ceramics, and beyond.