materforge 0.6.5

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.parsing.api 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
results = mat.evaluate(T, 500.0)
print(results['heat_capacity'])   # float

Property Inversion

from materforge.algorithms.piecewise_inverter import PiecewiseInverter
import sympy as sp
from materforge.parsing.api 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