materforge 0.6.4

A high-performance Python library for material simulation and analysis

MaterForge - Materials Formulation Engine with Python

A high-performance Python library for material simulation and analysis. MaterForge enables efficient modeling of pure metals and alloys through YAML configuration files, providing symbolic and numerical property evaluation for various material properties.

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

• Modular Architecture: Clean separation with algorithms, parsing, and visualization modules
• Flexible Material Definition: Support for both pure metals and alloys
• YAML-Driven Configuration: Define materials using intuitive YAML files
• Temperature-Dependent Properties: Support for complex temperature-dependent material properties
• Symbolic Mathematics: Built on SymPy for precise mathematical expressions
• Piecewise Functions: Advanced piecewise function support with regression capabilities
• Property Inversion: Create inverse functions for energy density and other properties
• Visualization: Automatic plotting of material properties with customizable options
• Multiple Property Types: Constants, step functions, file-based data, key-value pairs, 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

# Create a material with symbolic temperature
T = sp.Symbol('T')

# Load an example material (see examples/myAlloy.yaml)
material = create_material('examples/myAlloy.yaml', T, enable_plotting=True)

# Access symbolic property expressions
print(f"Heat capacity: {material.heat_capacity}")
print(f"Density:       {material.density}")

Working with Piecewise Inverse Functions

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

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

if hasattr(material, 'energy_density'):
    E = sp.Symbol('E')
    inverse_func = PiecewiseInverter.create_energy_density_inverse(material, 'E')

    # Test round-trip accuracy
    test_temp = 500.0
    energy_val = float(material.energy_density.subs(T, test_temp))
    recovered_temp = float(inverse_func.subs(E, energy_val))
    print(f"Round-trip: T={test_temp} -> E={energy_val:.2e} -> T={recovered_temp:.2f}")

📋 YAML Configuration Format

Supported Property Types

• CONSTANT_VALUE: Simple numeric values
• FILE_IMPORT: Data loaded from CSV/Excel/text files
• TABULAR_DATA: Temperature and corresponding property value pairs
• STEP_FUNCTION: Discontinuous transitions
• PIECEWISE_EQUATION: Symbolic equations over temperature ranges
• COMPUTED_PROPERTY: Properties calculated from other properties

See the YAML schema documentation for detailed configuration options.

YAML configuration examples:

• Test alloy (standalone example)
• Pure metal - Aluminum
• Alloy - Steel 1.4301 (full data)

📚 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 · Energy-Temperature Conversion
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 only linear piecewise functions
• 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 material simulation with Python