API Reference

MaterForge - Materials Formulation Engine with Python

A high-performance Python library for material property modeling and analysis. MaterForge provides comprehensive tools for defining, processing, and evaluating material properties as functions of temperature and other dependencies.

Key Features: - Temperature-dependent material property modeling - Multiple property definition formats (YAML-based) - Symbolic mathematics integration with SymPy - Piecewise function creation and evaluation - Material property visualization - Regression and data analysis capabilities - Integration with numerical simulation frameworks

Main Components: - Core: Material definitions and fundamental data structures - Parsing: YAML configuration parsing and property processing - Algorithms: Mathematical operations and property computations - Visualization: Property plotting and analysis tools - Data: Material databases and physical constants

class materforge.ChemicalElement(name: str, atomic_number: float, atomic_mass: float, melting_temperature: float, boiling_temperature: float, latent_heat_of_fusion: float, latent_heat_of_vaporization: float)[source]

Bases: object

Parameters:

  • name (str)

  • atomic_number (float)

  • atomic_mass (float)

  • melting_temperature (float)

  • boiling_temperature (float)

  • latent_heat_of_fusion (float)

  • latent_heat_of_vaporization (float)

atomic_mass: float
atomic_number: float
boiling_temperature: float
latent_heat_of_fusion: float
latent_heat_of_vaporization: float
melting_temperature: float
name: str
class materforge.Material(name, material_type, elements, composition, melting_temperature=None, boiling_temperature=None, solidus_temperature=None, liquidus_temperature=None, initial_boiling_temperature=None, final_boiling_temperature=None, bulk_modulus=None, density=None, dynamic_viscosity=None, elastic_modulus=None, electrical_conductivity=None, electrical_resistivity=None, energy_density=None, energy_density_solidus=None, energy_density_liquidus=None, fracture_toughness=None, hardness=None, heat_capacity=None, heat_conductivity=None, kinematic_viscosity=None, latent_heat_of_fusion=None, latent_heat_of_vaporization=None, magnetic_permeability=None, melting_point_pressure=None, poisson_ratio=None, shear_modulus=None, specific_enthalpy=None, surface_tension=None, thermal_diffusivity=None, thermal_expansion_coefficient=None, ultimate_tensile_strength=None, viscosity=None, yield_strength=None)[source]

Bases: object

Represents a material with its composition and properties.

This class supports both pure metals and alloys with comprehensive temperature validation and property calculation.

Parameters:

  • name (str)

  • material_type (str)

  • elements (List[ChemicalElement])

  • composition (ndarray | List[float] | Tuple)

  • melting_temperature (Float | None)

  • boiling_temperature (Float | None)

  • solidus_temperature (Float | None)

  • liquidus_temperature (Float | None)

  • initial_boiling_temperature (Float | None)

  • final_boiling_temperature (Float | None)

  • bulk_modulus (Float | None)

  • density (Expr)

  • dynamic_viscosity (Expr)

  • elastic_modulus (Expr | None)

  • electrical_conductivity (Expr | None)

  • electrical_resistivity (Expr | None)

  • energy_density (Piecewise | Expr | None)

  • energy_density_solidus (Float)

  • energy_density_liquidus (Float)

  • fracture_toughness (Expr | None)

  • hardness (Expr | None)

  • heat_capacity (Expr)

  • heat_conductivity (Expr)

  • kinematic_viscosity (Expr)

  • latent_heat_of_fusion (Expr)

  • latent_heat_of_vaporization (Expr)

  • magnetic_permeability (Expr | None)

  • melting_point_pressure (Float | None)

  • poisson_ratio (Float | None)

  • shear_modulus (Expr | None)

  • specific_enthalpy (Expr)

  • surface_tension (Expr)

  • thermal_diffusivity (Expr)

  • thermal_expansion_coefficient (Expr)

  • ultimate_tensile_strength (Expr | None)

  • viscosity (Expr)

  • yield_strength (Expr | None)

MAX_BOILING_TEMP = 6203.0
MAX_LIQUIDUS_TEMP = 2200.0
MAX_MELTING_TEMP = 3695.0
MAX_SOLIDUS_TEMP = 2000.0
MIN_BOILING_TEMP = 630.0
MIN_LIQUIDUS_TEMP = 300.0
MIN_MELTING_TEMP = 302.0
MIN_SOLIDUS_TEMP = 250.0
atomic_mass: float | None = None
atomic_number: float | None = None
boiling_point()[source]

Get the boiling point.

For pure metals, returns boiling_temperature. For alloys, returns initial_boiling_temperature. :returns: Boiling point temperature

Return type:

Float

boiling_temperature: Float | None = None
bulk_modulus: Float | None = None
composition: ndarray | List[float] | Tuple
density: Expr = None
dynamic_viscosity: Expr = None
elastic_modulus: Expr | None = None
electrical_conductivity: Expr | None = None
electrical_resistivity: Expr | None = None
elements: List[ChemicalElement]
energy_density: Piecewise | Expr | None = None
energy_density_liquidus: Float = None
energy_density_solidus: Float = None
evaluate_properties_at_temperature(temperature, properties=None, include_constants=True)[source]

Evaluate all or specified material properties at a given temperature.

Parameters:

  • temperature (float | int) – Temperature value in Kelvin

  • properties (List[str] | None) – List of specific property names to evaluate. If None, evaluates all properties.

  • include_constants (bool) – Whether to include constant properties in the result

Returns:

Dictionary mapping property names to their evaluated values

Return type:

Dict[str, float]

Examples

# Evaluate all properties values = material.evaluate_properties_at_temperature(500.0)

# Evaluate specific properties values = material.evaluate_properties_at_temperature(500.0, [‘density’, ‘heat_capacity’])

# Exclude constants values = material.evaluate_properties_at_temperature(500.0, include_constants=False)

final_boiling_temperature: Float | None = None
fracture_toughness: Expr | None = None
hardness: Expr | None = None
heat_capacity: Expr = None
heat_conductivity: Expr = None
initial_boiling_temperature: Float | None = None
kinematic_viscosity: Expr = None
latent_heat_of_fusion: Expr = None
latent_heat_of_vaporization: Expr = None
liquidus_temperature: Float | None = None
magnetic_permeability: Expr | None = None
material_type: str
melting_point()[source]

Get the melting point.

For pure metals, returns melting_temperature. For alloys, returns solidus_temperature. :returns: Melting point temperature

Return type:

Float

melting_point_pressure: Float | None = None
melting_temperature: Float | None = None
name: str
poisson_ratio: Float | None = None
shear_modulus: Expr | None = None
solidification_interval()[source]

Get the solidification interval for alloys. :returns: Tuple of (solidus_temperature, liquidus_temperature)

Raises:

ValueError – If called on a pure metal

Return type:

Tuple[Float, Float]

solidus_temperature: Float | None = None
specific_enthalpy: Expr = None
surface_tension: Expr = None
thermal_diffusivity: Expr = None
thermal_expansion_coefficient: Expr = None
ultimate_tensile_strength: Expr | None = None
viscosity: Expr = None
yield_strength: Expr | None = None
class materforge.PiecewiseBuilder[source]

Bases: object

Centralized piecewise function creation with different strategies.

static build_from_data(temp_array, prop_array, T, config, prop_name)[source]

Main entry point for data-based piecewise creation. :param temp_array: Temperature data points :param prop_array: Property values corresponding to temperatures :param T: Temperature symbol for the piecewise function :param config: Configuration dictionary containing bounds and regression settings :param prop_name: Name of the property (for logging and error messages)

Returns:

Symbolic piecewise function

Return type:

sp.Piecewise

Parameters:
static build_from_formulas(temp_points, equations, T, lower_bound_type='constant', upper_bound_type='constant')[source]

Create piecewise from symbolic equations. :param temp_points: Temperature breakpoints :param equations: List of symbolic expressions (strings or SymPy expressions) :param T: Temperature symbol :param lower_bound_type: Boundary behavior below first breakpoint :param upper_bound_type: Boundary behavior above last breakpoint

Returns:

Symbolic piecewise function

Return type:

sp.Piecewise

Parameters:

  • temp_points (ndarray)

  • equations (List[str | Expr])

  • T (Symbol)

  • lower_bound_type (str)

  • upper_bound_type (str)

class materforge.PiecewiseInverter(tolerance=1e-12)[source]

Bases: object

Creates inverse functions for linear piecewise functions only. Simplified version that supports only degree 1 polynomial.

Parameters:

tolerance (float)

static create_energy_density_inverse(material, output_symbol_name='E')[source]

Create inverse function for energy density: T = f_inv(E) :param material: Material object with energy_density property :param output_symbol_name: Symbol name for energy density (default: ‘E’)

Returns:

Inverse piecewise function

Raises:

ValueError – If energy density is not linear piecewise

Parameters:

output_symbol_name (str)

Return type:

Piecewise

static create_inverse(piecewise_func, input_symbol, output_symbol, tolerance=1e-12)[source]

Create the inverse of a linear piecewise function.

This static method provides a convenient interface for creating inverse functions without requiring explicit instantiation of PiecewiseInverter. :param piecewise_func: The original piecewise function E = f(T) :param input_symbol: Original input symbol (e.g., T) :param output_symbol: Output symbol for inverse function (e.g., E) :param tolerance: Numerical tolerance for inversion stability (default: 1e-12)

Returns:

Inverse piecewise function T = f_inv(E)

Raises:

ValueError – If any piece has degree > 1

Parameters:

  • piecewise_func (Piecewise | Expr)

  • input_symbol (Symbol | Basic)

  • output_symbol (Symbol | Basic)

  • tolerance (float)

Return type:

Piecewise

Examples

>>> T = sp.Symbol('T')
>>> E = sp.Symbol('E')
>>> piecewise_function = sp.Piecewise((2*T + 100, T < 500), (3*T - 400, True))
>>> inverse = PiecewiseInverter.create_inverse(piecewise_function, T, E)
class materforge.PropertyProcessor[source]

Bases: PropertyProcessorBase

Main orchestrator for processing different property types for material objects.

This class coordinates the processing of various property types by delegating to specialized handlers for each property type.

process_properties(material, dependency, properties, categorized_properties, base_dir, visualizer)[source]

Process all properties for the material.

Parameters:
Return type:

None

class materforge.PropertyType(*values)[source]

Bases: Enum

COMPUTED_PROPERTY = 6
CONSTANT_VALUE = 1
FILE_IMPORT = 3
INVALID = 7
PIECEWISE_EQUATION = 5
STEP_FUNCTION = 2
TABULAR_DATA = 4
class materforge.PropertyVisualizer(parser)[source]

Bases: object

Handles visualization of material properties.

initialize_plots()[source]

Initialize plots only if visualization is enabled.

Return type:

None

is_visualization_enabled()[source]

Check if visualization is currently enabled.

Return type:

bool

reset_visualization_tracking()[source]
Return type:

None

save_property_plots()[source]

Save plots only if visualization is enabled and plots exist.

Return type:

None

static setup_style()[source]
Return type:

None

visualize_property(material, prop_name, T, prop_type, x_data=None, y_data=None, has_regression=False, simplify_type=None, degree=1, segments=1, lower_bound=None, upper_bound=None, lower_bound_type='constant', upper_bound_type='constant')[source]

Visualize a single property.

Parameters:
Return type:

None

class materforge.SymbolRegistry[source]

Bases: object

Registry for SymPy symbols to ensure uniqueness.

classmethod clear()[source]

Clear all registered symbols.

Return type:

None

classmethod get(name)[source]

Get or create a symbol with the given name.

Parameters:

name (str)

Return type:

Symbol

classmethod get_all()[source]

Get all registered symbols.

Return type:

Dict[str, Symbol]

materforge.create_material(yaml_path, dependency, enable_plotting=True)[source]

Create material instance from YAML configuration file.

This function serves as the main entry point for creating material objects from YAML configuration files. It handles the parsing of the configuration and creation of the material with the specified temperature.

Parameters:

  • yaml_path (Union[str, Path]) – Path to the YAML configuration file

  • dependency (sp.Symbol) – Sympy symbol for property evaluation. Use a symbolic variable (e.g., sp.Symbol(‘T’) or sp.Symbol(‘u_C’)) for symbolic temperature expressions

  • enable_plotting (bool, optional) – Whether to generate visualization plots (default: True)

Returns:

The material instance with all properties initialized

Return type:

Material

Raises:

  • FileNotFoundError – If the YAML file doesn’t exist

  • ValueError – If the YAML content is invalid or material creation fails

  • TypeError – If temperature parameter has invalid type

Notes

In YAML files, always use ‘T’ as the temperature variable in equations. The system will automatically substitute this with your provided symbol.

Examples

Create a material with symbolic temperature expressions:

>>> import sympy as sp
>>> T = sp.Symbol('T')
>>> material = create_material('steel.yaml', T)
>>> print(material.name)
Steel

Create a material with a custom temperature symbol:

>>> u_C = sp.Symbol('u_C')
>>> material_copper = create_material('copper.yaml', u_C)
materforge.ensure_ascending_order(temp_array, *value_arrays)[source]

Ensure temperature array is in ascending order, flipping all provided arrays if needed.

Parameters:
Return type:

Tuple[ndarray, …]

materforge.get_material_info(yaml_path)[source]

Get basic information about a material configuration without full processing. :param yaml_path: Path to the YAML configuration file

Returns:

Dictionary containing material information including:

  • name: Material name

  • material_type: Type of material (pure_metal or alloy)

  • composition: Element composition dictionary

  • properties: List of available property names

  • total_properties: Number of properties defined

  • property_types: Count of each property type

  • Temperature properties based on material type

Return type:

Dict

Raises:
Parameters:

yaml_path (str | Path)

Example

info = get_material_info(‘steel.yaml’) print(f”Material: {info[‘name’]}”) print(f”Properties: {info[‘total_properties’]}”) print(f”Type: {info[‘material_type’]}”)

materforge.get_supported_properties()[source]

Get a list of all supported material properties.

Returns:

List of strings representing valid property names that can be defined in YAML files

Return type:

List[str]

Examples

>>> props = get_supported_properties()
>>> print(f"Supported properties: {len(props)}")
Supported properties: 12
>>> for prop in props[:3]:
...     print(f"  - {prop}")
  - density
  - heat_capacity
  - thermal_conductivity
materforge.interpolate_value(T, x_array, y_array, lower_bound_type, upper_bound_type)[source]

Interpolate a value at temperature T using the provided data arrays.

Parameters:
Return type:

float

materforge.validate_yaml_file(yaml_path)[source]

Validate a YAML file without creating the material. :param yaml_path: Path to the YAML configuration file to validate

Returns:

True if the file is valid

Return type:

bool

Raises:
Parameters:

yaml_path (str | Path)

Example

try:

is_valid = validate_yaml_file(‘steel.yaml’) print(f”YAML file is valid: {is_valid}”)

except ValueError as e:

print(f”Validation failed: {e}”)

Core Module

Core data structures and material definitions.

This module contains the fundamental classes and interfaces that define materials, chemical elements, and the core abstractions used throughout the PyMatLib library.

class materforge.core.ChemicalElement(name: str, atomic_number: float, atomic_mass: float, melting_temperature: float, boiling_temperature: float, latent_heat_of_fusion: float, latent_heat_of_vaporization: float)[source]

Bases: object

Parameters:

  • name (str)

  • atomic_number (float)

  • atomic_mass (float)

  • melting_temperature (float)

  • boiling_temperature (float)

  • latent_heat_of_fusion (float)

  • latent_heat_of_vaporization (float)

atomic_mass: float
atomic_number: float
boiling_temperature: float
latent_heat_of_fusion: float
latent_heat_of_vaporization: float
melting_temperature: float
name: str
class materforge.core.Material(name, material_type, elements, composition, melting_temperature=None, boiling_temperature=None, solidus_temperature=None, liquidus_temperature=None, initial_boiling_temperature=None, final_boiling_temperature=None, bulk_modulus=None, density=None, dynamic_viscosity=None, elastic_modulus=None, electrical_conductivity=None, electrical_resistivity=None, energy_density=None, energy_density_solidus=None, energy_density_liquidus=None, fracture_toughness=None, hardness=None, heat_capacity=None, heat_conductivity=None, kinematic_viscosity=None, latent_heat_of_fusion=None, latent_heat_of_vaporization=None, magnetic_permeability=None, melting_point_pressure=None, poisson_ratio=None, shear_modulus=None, specific_enthalpy=None, surface_tension=None, thermal_diffusivity=None, thermal_expansion_coefficient=None, ultimate_tensile_strength=None, viscosity=None, yield_strength=None)[source]

Bases: object

Represents a material with its composition and properties.

This class supports both pure metals and alloys with comprehensive temperature validation and property calculation.

Parameters:

  • name (str)

  • material_type (str)

  • elements (List[ChemicalElement])

  • composition (ndarray | List[float] | Tuple)

  • melting_temperature (Float | None)

  • boiling_temperature (Float | None)

  • solidus_temperature (Float | None)

  • liquidus_temperature (Float | None)

  • initial_boiling_temperature (Float | None)

  • final_boiling_temperature (Float | None)

  • bulk_modulus (Float | None)

  • density (Expr)

  • dynamic_viscosity (Expr)

  • elastic_modulus (Expr | None)

  • electrical_conductivity (Expr | None)

  • electrical_resistivity (Expr | None)

  • energy_density (Piecewise | Expr | None)

  • energy_density_solidus (Float)

  • energy_density_liquidus (Float)

  • fracture_toughness (Expr | None)

  • hardness (Expr | None)

  • heat_capacity (Expr)

  • heat_conductivity (Expr)

  • kinematic_viscosity (Expr)

  • latent_heat_of_fusion (Expr)

  • latent_heat_of_vaporization (Expr)

  • magnetic_permeability (Expr | None)

  • melting_point_pressure (Float | None)

  • poisson_ratio (Float | None)

  • shear_modulus (Expr | None)

  • specific_enthalpy (Expr)

  • surface_tension (Expr)

  • thermal_diffusivity (Expr)

  • thermal_expansion_coefficient (Expr)

  • ultimate_tensile_strength (Expr | None)

  • viscosity (Expr)

  • yield_strength (Expr | None)

MAX_BOILING_TEMP = 6203.0
MAX_LIQUIDUS_TEMP = 2200.0
MAX_MELTING_TEMP = 3695.0
MAX_SOLIDUS_TEMP = 2000.0
MIN_BOILING_TEMP = 630.0
MIN_LIQUIDUS_TEMP = 300.0
MIN_MELTING_TEMP = 302.0
MIN_SOLIDUS_TEMP = 250.0
atomic_mass: float | None = None
atomic_number: float | None = None
boiling_point()[source]

Get the boiling point.

For pure metals, returns boiling_temperature. For alloys, returns initial_boiling_temperature. :returns: Boiling point temperature

Return type:

Float

boiling_temperature: Float | None = None
bulk_modulus: Float | None = None
composition: ndarray | List[float] | Tuple
density: Expr = None
dynamic_viscosity: Expr = None
elastic_modulus: Expr | None = None
electrical_conductivity: Expr | None = None
electrical_resistivity: Expr | None = None
elements: List[ChemicalElement]
energy_density: Piecewise | Expr | None = None
energy_density_liquidus: Float = None
energy_density_solidus: Float = None
evaluate_properties_at_temperature(temperature, properties=None, include_constants=True)[source]

Evaluate all or specified material properties at a given temperature.

Parameters:

  • temperature (float | int) – Temperature value in Kelvin

  • properties (List[str] | None) – List of specific property names to evaluate. If None, evaluates all properties.

  • include_constants (bool) – Whether to include constant properties in the result

Returns:

Dictionary mapping property names to their evaluated values

Return type:

Dict[str, float]

Examples

# Evaluate all properties values = material.evaluate_properties_at_temperature(500.0)

# Evaluate specific properties values = material.evaluate_properties_at_temperature(500.0, [‘density’, ‘heat_capacity’])

# Exclude constants values = material.evaluate_properties_at_temperature(500.0, include_constants=False)

final_boiling_temperature: Float | None = None
fracture_toughness: Expr | None = None
hardness: Expr | None = None
heat_capacity: Expr = None
heat_conductivity: Expr = None
initial_boiling_temperature: Float | None = None
kinematic_viscosity: Expr = None
latent_heat_of_fusion: Expr = None
latent_heat_of_vaporization: Expr = None
liquidus_temperature: Float | None = None
magnetic_permeability: Expr | None = None
material_type: str
melting_point()[source]

Get the melting point.

For pure metals, returns melting_temperature. For alloys, returns solidus_temperature. :returns: Melting point temperature

Return type:

Float

melting_point_pressure: Float | None = None
melting_temperature: Float | None = None
name: str
poisson_ratio: Float | None = None
shear_modulus: Expr | None = None
solidification_interval()[source]

Get the solidification interval for alloys. :returns: Tuple of (solidus_temperature, liquidus_temperature)

Raises:

ValueError – If called on a pure metal

Return type:

Tuple[Float, Float]

solidus_temperature: Float | None = None
specific_enthalpy: Expr = None
surface_tension: Expr = None
thermal_diffusivity: Expr = None
thermal_expansion_coefficient: Expr = None
ultimate_tensile_strength: Expr | None = None
viscosity: Expr = None
yield_strength: Expr | None = None
exception materforge.core.MaterialCompositionError(message)[source]

Bases: MaterialError

Exception raised when material composition validation fails.

exception materforge.core.MaterialError(message)[source]

Bases: Exception

Base exception for all material-related errors.

exception materforge.core.MaterialTemperatureError(message)[source]

Bases: MaterialError

Exception raised when material temperature validation fails.

class materforge.core.SymbolRegistry[source]

Bases: object

Registry for SymPy symbols to ensure uniqueness.

classmethod clear()[source]

Clear all registered symbols.

Return type:

None

classmethod get(name)[source]

Get or create a symbol with the given name.

Parameters:

name (str)

Return type:

Symbol

classmethod get_all()[source]

Get all registered symbols.

Return type:

Dict[str, Symbol]

Material Class

class materforge.Material(name, material_type, elements, composition, melting_temperature=None, boiling_temperature=None, solidus_temperature=None, liquidus_temperature=None, initial_boiling_temperature=None, final_boiling_temperature=None, bulk_modulus=None, density=None, dynamic_viscosity=None, elastic_modulus=None, electrical_conductivity=None, electrical_resistivity=None, energy_density=None, energy_density_solidus=None, energy_density_liquidus=None, fracture_toughness=None, hardness=None, heat_capacity=None, heat_conductivity=None, kinematic_viscosity=None, latent_heat_of_fusion=None, latent_heat_of_vaporization=None, magnetic_permeability=None, melting_point_pressure=None, poisson_ratio=None, shear_modulus=None, specific_enthalpy=None, surface_tension=None, thermal_diffusivity=None, thermal_expansion_coefficient=None, ultimate_tensile_strength=None, viscosity=None, yield_strength=None)[source]

Bases: object

Represents a material with its composition and properties.

This class supports both pure metals and alloys with comprehensive temperature validation and property calculation.

Parameters:

  • name (str)

  • material_type (str)

  • elements (List[ChemicalElement])

  • composition (ndarray | List[float] | Tuple)

  • melting_temperature (Float | None)

  • boiling_temperature (Float | None)

  • solidus_temperature (Float | None)

  • liquidus_temperature (Float | None)

  • initial_boiling_temperature (Float | None)

  • final_boiling_temperature (Float | None)

  • bulk_modulus (Float | None)

  • density (Expr)

  • dynamic_viscosity (Expr)

  • elastic_modulus (Expr | None)

  • electrical_conductivity (Expr | None)

  • electrical_resistivity (Expr | None)

  • energy_density (Piecewise | Expr | None)

  • energy_density_solidus (Float)

  • energy_density_liquidus (Float)

  • fracture_toughness (Expr | None)

  • hardness (Expr | None)

  • heat_capacity (Expr)

  • heat_conductivity (Expr)

  • kinematic_viscosity (Expr)

  • latent_heat_of_fusion (Expr)

  • latent_heat_of_vaporization (Expr)

  • magnetic_permeability (Expr | None)

  • melting_point_pressure (Float | None)

  • poisson_ratio (Float | None)

  • shear_modulus (Expr | None)

  • specific_enthalpy (Expr)

  • surface_tension (Expr)

  • thermal_diffusivity (Expr)

  • thermal_expansion_coefficient (Expr)

  • ultimate_tensile_strength (Expr | None)

  • viscosity (Expr)

  • yield_strength (Expr | None)

MAX_BOILING_TEMP = 6203.0
MAX_LIQUIDUS_TEMP = 2200.0
MAX_MELTING_TEMP = 3695.0
MAX_SOLIDUS_TEMP = 2000.0
MIN_BOILING_TEMP = 630.0
MIN_LIQUIDUS_TEMP = 300.0
MIN_MELTING_TEMP = 302.0
MIN_SOLIDUS_TEMP = 250.0
atomic_mass: float | None = None
atomic_number: float | None = None
boiling_point()[source]

Get the boiling point.

For pure metals, returns boiling_temperature. For alloys, returns initial_boiling_temperature. :returns: Boiling point temperature

Return type:

Float

boiling_temperature: Float | None = None
bulk_modulus: Float | None = None
composition: ndarray | List[float] | Tuple
density: Expr = None
dynamic_viscosity: Expr = None
elastic_modulus: Expr | None = None
electrical_conductivity: Expr | None = None
electrical_resistivity: Expr | None = None
elements: List[ChemicalElement]
energy_density: Piecewise | Expr | None = None
energy_density_liquidus: Float = None
energy_density_solidus: Float = None
evaluate_properties_at_temperature(temperature, properties=None, include_constants=True)[source]

Evaluate all or specified material properties at a given temperature.

Parameters:

  • temperature (float | int) – Temperature value in Kelvin

  • properties (List[str] | None) – List of specific property names to evaluate. If None, evaluates all properties.

  • include_constants (bool) – Whether to include constant properties in the result

Returns:

Dictionary mapping property names to their evaluated values

Return type:

Dict[str, float]

Examples

# Evaluate all properties values = material.evaluate_properties_at_temperature(500.0)

# Evaluate specific properties values = material.evaluate_properties_at_temperature(500.0, [‘density’, ‘heat_capacity’])

# Exclude constants values = material.evaluate_properties_at_temperature(500.0, include_constants=False)

final_boiling_temperature: Float | None = None
fracture_toughness: Expr | None = None
hardness: Expr | None = None
heat_capacity: Expr = None
heat_conductivity: Expr = None
initial_boiling_temperature: Float | None = None
kinematic_viscosity: Expr = None
latent_heat_of_fusion: Expr = None
latent_heat_of_vaporization: Expr = None
liquidus_temperature: Float | None = None
magnetic_permeability: Expr | None = None
material_type: str
melting_point()[source]

Get the melting point.

For pure metals, returns melting_temperature. For alloys, returns solidus_temperature. :returns: Melting point temperature

Return type:

Float

melting_point_pressure: Float | None = None
melting_temperature: Float | None = None
name: str
poisson_ratio: Float | None = None
shear_modulus: Expr | None = None
solidification_interval()[source]

Get the solidification interval for alloys. :returns: Tuple of (solidus_temperature, liquidus_temperature)

Raises:

ValueError – If called on a pure metal

Return type:

Tuple[Float, Float]

solidus_temperature: Float | None = None
specific_enthalpy: Expr = None
surface_tension: Expr = None
thermal_diffusivity: Expr = None
thermal_expansion_coefficient: Expr = None
ultimate_tensile_strength: Expr | None = None
viscosity: Expr = None
yield_strength: Expr | None = None

Chemical Elements

class materforge.ChemicalElement(name: str, atomic_number: float, atomic_mass: float, melting_temperature: float, boiling_temperature: float, latent_heat_of_fusion: float, latent_heat_of_vaporization: float)[source]

Bases: object

Parameters:

  • name (str)

  • atomic_number (float)

  • atomic_mass (float)

  • melting_temperature (float)

  • boiling_temperature (float)

  • latent_heat_of_fusion (float)

  • latent_heat_of_vaporization (float)

atomic_mass: float
atomic_number: float
boiling_temperature: float
latent_heat_of_fusion: float
latent_heat_of_vaporization: float
melting_temperature: float
name: str

Algorithms Module

Core computational algorithms for materials property processing.

This module provides mathematical algorithms for processing material properties, including interpolation, regression, piecewise function construction, and property inversion operations.

class materforge.algorithms.PiecewiseBuilder[source]

Bases: object

Centralized piecewise function creation with different strategies.

static build_from_data(temp_array, prop_array, T, config, prop_name)[source]

Main entry point for data-based piecewise creation. :param temp_array: Temperature data points :param prop_array: Property values corresponding to temperatures :param T: Temperature symbol for the piecewise function :param config: Configuration dictionary containing bounds and regression settings :param prop_name: Name of the property (for logging and error messages)

Returns:

Symbolic piecewise function

Return type:

sp.Piecewise

Parameters:
static build_from_formulas(temp_points, equations, T, lower_bound_type='constant', upper_bound_type='constant')[source]

Create piecewise from symbolic equations. :param temp_points: Temperature breakpoints :param equations: List of symbolic expressions (strings or SymPy expressions) :param T: Temperature symbol :param lower_bound_type: Boundary behavior below first breakpoint :param upper_bound_type: Boundary behavior above last breakpoint

Returns:

Symbolic piecewise function

Return type:

sp.Piecewise

Parameters:

  • temp_points (ndarray)

  • equations (List[str | Expr])

  • T (Symbol)

  • lower_bound_type (str)

  • upper_bound_type (str)

class materforge.algorithms.PiecewiseInverter(tolerance=1e-12)[source]

Bases: object

Creates inverse functions for linear piecewise functions only. Simplified version that supports only degree 1 polynomial.

Parameters:

tolerance (float)

static create_energy_density_inverse(material, output_symbol_name='E')[source]

Create inverse function for energy density: T = f_inv(E) :param material: Material object with energy_density property :param output_symbol_name: Symbol name for energy density (default: ‘E’)

Returns:

Inverse piecewise function

Raises:

ValueError – If energy density is not linear piecewise

Parameters:

output_symbol_name (str)

Return type:

Piecewise

static create_inverse(piecewise_func, input_symbol, output_symbol, tolerance=1e-12)[source]

Create the inverse of a linear piecewise function.

This static method provides a convenient interface for creating inverse functions without requiring explicit instantiation of PiecewiseInverter. :param piecewise_func: The original piecewise function E = f(T) :param input_symbol: Original input symbol (e.g., T) :param output_symbol: Output symbol for inverse function (e.g., E) :param tolerance: Numerical tolerance for inversion stability (default: 1e-12)

Returns:

Inverse piecewise function T = f_inv(E)

Raises:

ValueError – If any piece has degree > 1

Parameters:

  • piecewise_func (Piecewise | Expr)

  • input_symbol (Symbol | Basic)

  • output_symbol (Symbol | Basic)

  • tolerance (float)

Return type:

Piecewise

Examples

>>> T = sp.Symbol('T')
>>> E = sp.Symbol('E')
>>> piecewise_function = sp.Piecewise((2*T + 100, T < 500), (3*T - 400, True))
>>> inverse = PiecewiseInverter.create_inverse(piecewise_function, T, E)
class materforge.algorithms.RegressionProcessor[source]

Bases: object

Handles all regression-related functionality.

static get_symbolic_conditions(pwlf_, x, lower_, upper_)[source]

Create symbolic conditions for a piecewise function from a pwlf fit.

Parameters:

  • pwlf_ (PiecewiseLinFit)

  • x (Symbol)

  • lower_ (str)

  • upper_ (str)

static get_symbolic_eqn(pwlf_, segment_number, x)[source]

Get symbolic equation for a specific segment.

Parameters:

  • pwlf_ (PiecewiseLinFit)

  • segment_number (int)

  • x (float | Symbol)

static process_regression(temp_array, prop_array, T, lower_bound_type, upper_bound_type, degree, segments, seed=13579)[source]

Centralized regression processing logic.

static process_regression_params(prop_config, prop_name, data_length)[source]

Process regression parameters from configuration.

Parameters:

  • prop_config (dict)

  • prop_name (str)

  • data_length (int)

Return type:

Tuple[bool, str | None, int | None, int | None]

materforge.algorithms.ensure_ascending_order(temp_array, *value_arrays)[source]

Ensure temperature array is in ascending order, flipping all provided arrays if needed.

Parameters:
Return type:

Tuple[ndarray, …]

materforge.algorithms.interpolate_value(T, x_array, y_array, lower_bound_type, upper_bound_type)[source]

Interpolate a value at temperature T using the provided data arrays.

Parameters:
Return type:

float

Parsing Module

Parsing and configuration modules for PyMatLib.

This package handles YAML parsing, property type detection, validation, and material creation from configuration files.

class materforge.parsing.MaterialYAMLParser(yaml_path)[source]

Bases: YAMLFileParser

Parser for material configuration files in YAML format.

Parameters:

yaml_path (str | Path)

VALID_YAML_PROPERTIES = {'bulk_modulus', 'density', 'dynamic_viscosity', 'elastic_modulus', 'electrical_conductivity', 'electrical_resistivity', 'energy_density', 'fracture_toughness', 'hardness', 'heat_capacity', 'heat_conductivity', 'kinematic_viscosity', 'latent_heat_of_fusion', 'latent_heat_of_vaporization', 'magnetic_permeability', 'poisson_ratio', 'shear_modulus', 'specific_enthalpy', 'surface_tension', 'thermal_diffusivity', 'thermal_expansion_coefficient', 'ultimate_tensile_strength', 'viscosity', 'yield_strength'}
create_material(dependency, enable_plotting=True)[source]

Create a Material instance from the parsed configuration and temperature.

Parameters:

  • dependency (float | Symbol)

  • enable_plotting (bool)

Return type:

Material

class materforge.parsing.PropertyProcessor[source]

Bases: PropertyProcessorBase

Main orchestrator for processing different property types for material objects.

This class coordinates the processing of various property types by delegating to specialized handlers for each property type.

process_properties(material, dependency, properties, categorized_properties, base_dir, visualizer)[source]

Process all properties for the material.

Parameters:
Return type:

None

class materforge.parsing.PropertyType(*values)[source]

Bases: Enum

COMPUTED_PROPERTY = 6
CONSTANT_VALUE = 1
FILE_IMPORT = 3
INVALID = 7
PIECEWISE_EQUATION = 5
STEP_FUNCTION = 2
TABULAR_DATA = 4
class materforge.parsing.PropertyTypeDetector[source]

Bases: object

Utility class for detecting and validating property types from configuration values.

DETECTION_RULES = [(<function PropertyTypeDetector.<lambda>>, PropertyType.FILE_IMPORT), (<function PropertyTypeDetector.<lambda>>, PropertyType.STEP_FUNCTION), (<function PropertyTypeDetector.<lambda>>, PropertyType.TABULAR_DATA), (<function PropertyTypeDetector.<lambda>>, PropertyType.PIECEWISE_EQUATION), (<function PropertyTypeDetector.<lambda>>, PropertyType.COMPUTED_PROPERTY)]
static determine_property_type(prop_name, config)[source]

Determines the property type using a declarative, rule-based approach.

Parameters:

  • prop_name (str)

  • config (Any)

Return type:

PropertyType

static validate_property_config(prop_name, config, prop_type)[source]

Performs strict validation based on the detected property type.

Parameters:

  • prop_name (str)

  • config (Any)

  • prop_type (PropertyType)

Return type:

None

materforge.parsing.create_material(yaml_path, dependency, enable_plotting=True)[source]

Create material instance from YAML configuration file.

This function serves as the main entry point for creating material objects from YAML configuration files. It handles the parsing of the configuration and creation of the material with the specified temperature.

Parameters:

  • yaml_path (Union[str, Path]) – Path to the YAML configuration file

  • dependency (sp.Symbol) – Sympy symbol for property evaluation. Use a symbolic variable (e.g., sp.Symbol(‘T’) or sp.Symbol(‘u_C’)) for symbolic temperature expressions

  • enable_plotting (bool, optional) – Whether to generate visualization plots (default: True)

Returns:

The material instance with all properties initialized

Return type:

Material

Raises:

  • FileNotFoundError – If the YAML file doesn’t exist

  • ValueError – If the YAML content is invalid or material creation fails

  • TypeError – If temperature parameter has invalid type

Notes

In YAML files, always use ‘T’ as the temperature variable in equations. The system will automatically substitute this with your provided symbol.

Examples

Create a material with symbolic temperature expressions:

>>> import sympy as sp
>>> T = sp.Symbol('T')
>>> material = create_material('steel.yaml', T)
>>> print(material.name)
Steel

Create a material with a custom temperature symbol:

>>> u_C = sp.Symbol('u_C')
>>> material_copper = create_material('copper.yaml', u_C)
materforge.parsing.evaluate_material_properties(material, temperature, properties=None, include_constants=True)[source]

Convenience function to evaluate material properties at a specific temperature.

This is a wrapper around Material.evaluate_properties_at_temperature() for functional-style usage. :param material: Material instance :param temperature: Temperature value in Kelvin :param properties: List of specific property names to evaluate. If None, evaluates all. :param include_constants: Whether to include constant properties in the result

Returns:

Dictionary mapping property names to their evaluated values

Return type:

Dict[str, float]

Raises:

ValueError – If material is not a Material instance or temperature is invalid

Parameters:

Examples

# Evaluate all properties values = evaluate_material_properties(material, 500.0) # Evaluate specific properties values = evaluate_material_properties(material, 500.0, [‘density’, ‘heat_capacity’]) # Get only temperature-dependent properties values = evaluate_material_properties(material, 500.0, include_constants=False)

materforge.parsing.get_material_info(yaml_path)[source]

Get basic information about a material configuration without full processing. :param yaml_path: Path to the YAML configuration file

Returns:

Dictionary containing material information including:

  • name: Material name

  • material_type: Type of material (pure_metal or alloy)

  • composition: Element composition dictionary

  • properties: List of available property names

  • total_properties: Number of properties defined

  • property_types: Count of each property type

  • Temperature properties based on material type

Return type:

Dict

Raises:
Parameters:

yaml_path (str | Path)

Example

info = get_material_info(‘steel.yaml’) print(f”Material: {info[‘name’]}”) print(f”Properties: {info[‘total_properties’]}”) print(f”Type: {info[‘material_type’]}”)

materforge.parsing.get_material_property_names(material)[source]

Get list of all available property names for a material instance. :param material: Material instance

Returns:

List of property names that exist (are not None) on the material

Return type:

List[str]

Raises:

ValueError – If material is not a Material instance

Parameters:

material (Material)

Example

material = create_material(‘steel.yaml’, dependency=sp.Symbol(‘T’)) available = get_material_property_names(material) print(f”Available properties: {available}”)

materforge.parsing.get_supported_properties()[source]

Get a list of all supported material properties.

Returns:

List of strings representing valid property names that can be defined in YAML files

Return type:

List[str]

Examples

>>> props = get_supported_properties()
>>> print(f"Supported properties: {len(props)}")
Supported properties: 12
>>> for prop in props[:3]:
...     print(f"  - {prop}")
  - density
  - heat_capacity
  - thermal_conductivity
materforge.parsing.validate_yaml_file(yaml_path)[source]

Validate a YAML file without creating the material. :param yaml_path: Path to the YAML configuration file to validate

Returns:

True if the file is valid

Return type:

bool

Raises:
Parameters:

yaml_path (str | Path)

Example

try:

is_valid = validate_yaml_file(‘steel.yaml’) print(f”YAML file is valid: {is_valid}”)

except ValueError as e:

print(f”Validation failed: {e}”)

Visualization Module

Visualization tools for material properties.

class materforge.visualization.PropertyVisualizer(parser)[source]

Bases: object

Handles visualization of material properties.

initialize_plots()[source]

Initialize plots only if visualization is enabled.

Return type:

None

is_visualization_enabled()[source]

Check if visualization is currently enabled.

Return type:

bool

reset_visualization_tracking()[source]
Return type:

None

save_property_plots()[source]

Save plots only if visualization is enabled and plots exist.

Return type:

None

static setup_style()[source]
Return type:

None

visualize_property(material, prop_name, T, prop_type, x_data=None, y_data=None, has_regression=False, simplify_type=None, degree=1, segments=1, lower_bound=None, upper_bound=None, lower_bound_type='constant', upper_bound_type='constant')[source]

Visualize a single property.

Parameters:
Return type:

None