materforge 0.8.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 of material properties with customizable options
• 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://i10git.cs.fau.de/rahil.doshi/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

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

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 · 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 demonstration applications that integrate MaterForge with waLBerla and pystencils. Because these dependencies are GPLv3-licensed, the apps directory is licensed under GPL-3.0-or-later. See 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.

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
• GitLab: i10git.cs.fau.de

---

🙏 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