materforge 0.10.0

A high-performance Python library for material simulation and analysis

MaterForge - Materials Formulation Engine with Python

A high-performance Python library for materials modeling and simulation. MaterForge enables efficient definition of any material - metals, alloys, polymers, ceramics, composites, or hypothetical materials - through YAML configuration files, providing symbolic and numerical property evaluation as a function of any SymPy symbol.

Documentation: https://materforge.readthedocs.io

Table of Contents

• Key Features
• Installation
• Quick Start
• YAML Configuration Format
• Documentation
• Contributing
• Known Limitations
• License
• Citation
• Support
• Acknowledgments

---

🚀 Key Features

• Schema-Agnostic Material Definition: Any material kind, any property name - the YAML schema drives everything with no hardcoded material types or required fields
• Dependency-Driven Properties: Properties expressed as symbolic functions of any independent variable - temperature, pressure, composition, strain, or any SymPy symbol
• Modular Architecture: Clean separation with algorithms, parsing, and visualization modules
• Symbolic Mathematics: Built on SymPy for precise mathematical expressions
• Piecewise Functions: Advanced piecewise function support with regression capabilities
• Property Inversion: Create inverse functions for any piecewise-linear property
• Visualization: Automatic plotting during a build, plus post-build, notebook-friendly helpers that return a Matplotlib Axes for fit, residual, and cross-material compare plots
• Fit-Quality Metrics: R², RMSE, MAE, and residuals for every data-backed property, so you can check how faithfully a fit reproduces its source data
• Multiple Property Types: Constants, step functions, file-based data, tabular data, piecewise equations, and computed properties
• Regression Analysis: Built-in piecewise linear fitting with configurable parameters

---

📦 Installation

Install from PyPI

pip install materforge

All required dependencies are installed automatically.

For contributors

Clone the repository and install in editable mode:

git clone https://github.com/rahildoshi97/materforge.git
cd materforge
pip install -e .

Note: The -e flag (--editable) installs the package by symlinking directly to the source directory. Changes to source files take effect immediately without reinstalling - intended for development only. Use pip install materforge for regular use.

---

🏃 Quick Start

Basic Material Creation

import sympy as sp
from materforge import create_material

# Any SymPy symbol works as the dependency variable
T = sp.Symbol('T')

# Load a material from YAML (see examples/myAlloy.yaml)
mat = create_material('examples/myAlloy.yaml', dependency=T, enable_plotting=True)

# Access symbolic property expressions directly
print(mat.heat_capacity)   # SymPy Piecewise expression in T
print(mat.density)         # 7000.0 (constant float)

# Evaluate all properties at a specific value (returns a new Material)
results = mat.evaluate(T, 500.0)
print(results.heat_capacity)   # float

Bundled Example Materials

MaterForge is designed for you to write your own YAML configs. For convenience, a few reference materials ship with the package and can be loaded by name - handy for demos and quick experiments:

import sympy as sp
from materforge import list_materials, load_material

print(list_materials())                       # ['1.4301', 'Al', 'Al2O3']
steel = load_material('1.4301', sp.Symbol('T'))

These are examples, not a curated database. See the bundled materials guide for details.

Command-Line Interface

Installing the package also provides a materforge command for working with YAML files straight from a shell - no Python required:

materforge list                       # bundled example materials
materforge validate my_material.yaml  # check a file is structurally valid
materforge info my_material.yaml       # name, properties, and property types
materforge plot my_material.yaml       # write a property figure
materforge evaluate my_material.yaml 500   # evaluate every property at T=500
materforge fit my_material.yaml         # R²/RMSE for every data-backed property

Each subcommand wraps the same public API shown above. See the CLI guide for the full reference.

Fast Evaluation Over Many Values

evaluate() is convenient for a single value. To sweep a range, compile the material once - each property is lambdified and cached, so an array is evaluated in a single vectorised call:

import numpy as np

evaluate = mat.compile()              # cache numeric callables once

evaluate(500.0)                       # scalar -> {'density': 7861.2, ...}
table = evaluate(np.linspace(300, 1800, 500))   # array -> dict of arrays
table['density'].shape                # (500,)

See the fast evaluation guide for details.

Assess Fit Quality & Visualize

Every data-backed property (file-import, tabular, or computed) keeps the points it was fit from, so you can score the fit and plot it after the build - no re-parsing:

import materforge as mf

# How well does each stored curve reproduce its source data?
print(mf.fit_quality(mat, 'heat_capacity'))     # R²=0.9996  RMSE=8.9  ...
report = mf.fit_report(mat)                      # dict: name -> FitQuality

# Plotting helpers return a Matplotlib Axes - they render inline in Jupyter and
# never save or close the figure, so you stay in control of styling and output:
mf.plot_property(mat, 'heat_capacity')           # fitted curve + the source points
mf.plot_residuals(mat, 'heat_capacity')          # residuals with a zero reference line
mf.compare_materials([steel, alloy], 'density')  # the same property, several materials

Fit quality measures the stored curve against its source points: for a property with regression: {simplify: pre/post} that is the genuine fit error; plain interpolation passes through every point, so it reads ~0. See the fit-quality and visualization guides.

Cached Builds

The slow part of create_material is the piecewise regression. MaterForge caches the built result on disk (keyed by the YAML, its data files, the dependency, and the library versions), so reloading an unchanged material skips the refit:

# First call builds and caches; later calls of the unchanged YAML are instant.
mat = create_material('steel.yaml', dependency=T)

On by default (a plotting build always rebuilds); disable with MATERFORGE_DISABLE_CACHE=1, relocate with MATERFORGE_CACHE_DIR, or empty it via clear_cache(). See the cache guide.

Property Inversion

from materforge.algorithms.piecewise_inverter import PiecewiseInverter
import sympy as sp
from materforge import create_material

T = sp.Symbol('T')
mat = create_material('examples/myAlloy.yaml', dependency=T)

if hasattr(mat, 'energy_density'):
    E = sp.Symbol('E')
    inverse = PiecewiseInverter.create_inverse(mat.energy_density, 'T', 'E')

    # Validate round-trip accuracy
    test_val = 500.0
    e = float(mat.energy_density.subs(T, test_val))
    recovered = float(inverse.subs(E, e))
    print(f"Round-trip: T={test_val} -> E={e:.2e} -> T={recovered:.2f}")

---

📋 YAML Configuration Format

Supported Property Types

• CONSTANT_VALUE: Single numeric value - not dependency-driven
• STEP_FUNCTION: Discontinuous transition at a scalar reference point
• FILE_IMPORT: Data loaded from CSV, Excel, or text files
• TABULAR_DATA: Explicit dependency-value pairs
• PIECEWISE_EQUATION: Symbolic equations over dependency variable ranges
• COMPUTED_PROPERTY: Properties derived from other defined properties

The symbol used in YAML equations (T) is a placeholder only - MaterForge substitutes it with whatever symbol you pass to create_material(..., dependency=symbol) at runtime.

See the YAML schema documentation for full configuration options.

Example YAML files:

• Example alloy
• Aluminum
• Steel 1.4301

---

📚 Documentation

Full documentation is available at https://materforge.readthedocs.io

The documentation follows the Diátaxis framework:

Type	Content
Tutorials	Getting Started · First Simulation
How-to Guides	Defining Material Properties · Assess Fit Quality · Visualize Properties · Property Inversion
Reference	API Reference · YAML Schema
Explanation	Design Philosophy · Material Properties

---

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details on how to get started.

---

🐛 Known Limitations

• Piecewise Inverter: Currently supports linear piecewise functions only (degree: 1)
• File Formats: Limited to CSV, Excel, and text files
• Memory Usage: Large datasets may require optimization for very high-resolution data
• Regression: Maximum 8 segments recommended for stability

---

📄 License

Core Library (BSD-3-Clause)

The MaterForge library itself (src/materforge/, examples/, tests/, docs/) is licensed under the BSD 3-Clause License. See the LICENSE file for full details.

Application Examples (GPL-3.0-or-later)

The apps/ directory contains two demonstration applications that integrate MaterForge with waLBerla and pystencils via code generation — apps/HeatEquationKernel/ (a heat-equation solver with a temperature-dependent material) and apps/CouetteFlow/ (a 3D thermal Couette flow LBM benchmark). Because these dependencies are GPLv3-licensed, the apps directory is licensed under GPL-3.0-or-later. See apps/README.md for the overview and apps/LICENSE for full details.

PyPI Distribution

pip install materforge includes only the BSD-3-Clause licensed core library. The GPL-licensed apps are excluded from the PyPI distribution — they need a C++/CMake/MPI toolchain plus waLBerla that pip cannot provide. To run the demo apps, get them from the source repository:

git clone https://github.com/rahildoshi97/materforge.git
cd materforge
git submodule update --init --recursive   # populates apps/walberla

See apps/README.md for build and run instructions.

Component	Location	License	In PyPI
Core library	src/materforge/	BSD-3-Clause	✅
Example scripts	examples/	BSD-3-Clause	❌
Tests	tests/	BSD-3-Clause	❌
Documentation	docs/	BSD-3-Clause	❌
Apps	apps/	GPL-3.0-or-later	❌

---

📖 Citation

If you use MaterForge in your research, please cite it using the information in our CITATION.cff file.

---

📞 Support

• Author: Rahil Doshi
• Email: [e-mail]
• Documentation: materforge.readthedocs.io
• Bug Tracker: GitHub Issues
• Source Code: GitHub

---

🙏 Acknowledgments

• Built with SymPy for symbolic mathematics
• Data handling powered by pandas
• Uses pwlf for piecewise linear fitting
• Visualization powered by Matplotlib
• YAML parsing with ruamel.yaml

---

MaterForge - Empowering materials simulation with Python