design_philosophy.md

Design Philosophy of pymatlib

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

Core Principles

pymatlib is built upon several core principles:

• Modularity: Clearly separated components for ease of maintenance, testing, and extensibility.
• Flexibility: Allow users to define material properties in various intuitive ways.
• Performance: Leverage symbolic computation and optimized C++ code generation for high-performance simulations.
• Transparency and Reproducibility: Clearly document material property definitions and computations to ensure reproducibility.

Layered Architecture

pymatlib follows a layered architecture to separate concerns clearly:

1. User Interface Layer (YAML Configuration)

• Provides a simple, human-readable format for defining alloys and their properties.
• Allows users to specify properties using multiple intuitive methods (constants, interpolation points, file-based data, computed properties).
• Ensures clarity, readability, and ease of use

2. Symbolic Representation Layer (SymPy)

• Uses symbolic mathematics (via SymPy) internally to represent material properties.
• Enables symbolic manipulation, simplification, and validation of property definitions.
• Facilitates automatic computation of derived properties.

3. Interpolation and Computation Layer (Python)

• Implements robust interpolation methods (interpolate_equidistant, interpolate_lookup) for evaluating temperature-dependent properties.
• Automatically analyzes input arrays (prepare_interpolation_arrays) to determine the optimal interpolation method based on data characteristics.
• Provides symbolic manipulation capabilities through SymPy for computed properties.

4. Code Generation Layer (C++)

• Uses InterpolationArrayContainer to generate optimized C++ code for efficient energy-to-temperature conversions.
• Automatically selects the best interpolation method (Binary Search or Double Lookup) based on data analysis results from Python.
• Integrates seamlessly with pystencils and waLBerla for high-performance simulations.

Separation Between Python and C++ Components

pymatlib separates responsibilities clearly between Python and C++ components:

Component	Responsibility	Implementation Language
YAML Configuration	User-friendly material property definitions	YAML
Symbolic Computation & Validation	Parsing YAML files, symbolic computations and validations (sympy)	Python
Interpolation Analysis	Determining optimal interpolation method based on data characteristics (prepare_interpolation_arrays)	Python
Code Generation	Generating optimized interpolation code (InterpolationArrayContainer) for high-performance simulations	C++
Simulation Execution	Running generated kernels within simulation frameworks (waLBerla/pystencils)	C++

This separation ensures:

• Flexibility in defining materials through easily editable YAML files
• Powerful symbolic manipulation capabilities in Python
• High-performance numerical computations in C++

Why YAML?

YAML was chosen as the primary configuration format because:

• It is human-readable and easy to edit manually
• It naturally supports nested structures required by complex material definitions
• It integrates smoothly with Python's ecosystem via libraries like PyYAML
• It allows referencing previously defined variables within the file (e.g., solidus_temperature, liquidus_temperature), reducing redundancy.

Integration with pystencils and waLBerla

pymatlib integrates closely with pystencils and waLBerla through the following workflow:

1. Symbolic Definition: Material properties are defined symbolically in pymatlib using YAML configurations.
2. Assignment Conversion: The assignment_converter function converts pymatlib's symbolic assignments into pystencils-compatible assignments.
3. Code Generation: pystencils generates optimized kernels from these assignments for numerical simulations.
4. Simulation execution: Generated kernels are executed within waLBerla frameworks for large-scale parallel simulations.

This integration allows pymatlib to leverage:

• Symbolic mathematics from sympy via pystencils
• Optimized stencil-based numerical kernels generated by pystencils-sfg
• High-performance parallel computing capabilities provided by waLBerla

Automatic Method Selection for Interpolation

A key design decision in pymatlib is automatic method selection for interpolation between energy density and temperature:

1. Analysis Phase (Python):

• The function prepare_interpolation_arrays() analyzes input arrays to determine if they're equidistant or not.
• Based on this analysis, it selects either Binary Search or Double Lookup as the preferred interpolation method.

2. Code Generation Phase (C++):

• The InterpolationArrayContainer class generates optimized C++ code that includes both interpolation methods (interpolateBS, interpolateDL) if applicable.
• A wrapper method (interpolate) is automatically generated to select the best available method at runtime without user intervention.

This ensures optimal performance without burdening users with manual selection decisions.

Extensibility

pymatlib is designed with extensibility in mind:

• Users can easily define new material properties or extend existing ones through YAML files without changing core code.
• New computational models or interpolation methods can be added at the Python layer without affecting existing functionality.
• The modular design allows easy integration with additional simulation frameworks beyond pystencils or waLBerla if needed.

Robustness and Error Handling

pymatlib includes comprehensive validation checks at every step:

YAML Parser Validation

• Ensures consistent units (SI units recommended).
• Checks monotonicity of temperature-energy arrays.
• Validates dependencies among computed properties.

Interpolation Validation

The interpolation functions validate:

• Array lengths match
• Arrays contain sufficient elements
• Arrays are strictly monotonic
• Energy density increases consistently with temperature

If any validation fails, clear error messages guide users toward correcting their configurations.

Performance Optimization Philosophy

Performance-critical numerical operations are implemented in optimized C++ code generated automatically from Python definitions. This approach provides:

1. Ease of use: Users define materials symbolically or numerically without worrying about low-level optimization details.
2. Automatic Optimization: pymatlib automatically selects optimal algorithms (Double Lookup vs Binary Search) based on data characteristics without user intervention.
3. High Performance: Generated kernels provide near-native performance suitable for large-scale simulations while maintaining flexibility in material definitions.