Load Bundled Example Materials

MaterForge is built around YAML configs that you write yourself - that is the whole point of the library, and the material definition guide walks through it. To make trying the API easier, the package also ships a few reference materials you can load by name without locating the installed file.

These bundled materials are examples, not a curated database. Use them for demos, quick experiments, and tests; for real work, define your own configs.

When to Use Which

There are two ways to load a material, and they cover different needs:

  • Your own config, anywhere on disk - pass a path to create_material. This is the normal workflow; keep the YAML wherever suits your project.

    from pathlib import Path
from materforge import create_material

yaml_path = Path(__file__).parent / "my_material.yaml"
mat = create_material(yaml_path, dependency=T)

  • One of the examples shipped with the package - pass a name to load_material (or get_material_path). These helpers only see the files bundled inside the installed package; they will not find a YAML sitting elsewhere on disk, so load_material("my_material") raises ValueError.

The catalog helpers sit on top of create_material as a convenience - they don’t replace it. validate_yaml_file and get_material_info likewise take a path and work with any file you point them at.

Listing What Is Available

from materforge import list_materials

print(list_materials())   # ['1.4301', 'Al', 'Al2O3']

The names are the YAML file stems: Al (aluminium), Al2O3 (alumina), and 1.4301 (the EN grade for AISI 304 stainless steel).

Loading a Material by Name

load_material is a thin wrapper around create_material for the shipped files. Matching is case-insensitive.

import sympy as sp
from materforge import load_material

T = sp.Symbol('T')
steel = load_material('1.4301', T)

print(steel)              # Material: 1.4301 (13 properties)
print(steel.heat_capacity)  # SymPy expression in T

# Evaluate at a temperature, as with any material
at_800 = steel.evaluate(T, 800.0)
print(float(at_800.heat_capacity))

Plotting is off by default here (unlike create_material), so loading an example never writes plot files next to the installed package. Pass enable_plotting=True if you want the plots.

Getting the File Path

When you would rather read or copy the YAML - for instance, to use a bundled file as the starting point for your own - ask for its path:

from materforge import get_material_path

path = get_material_path('Al')
print(path)               # .../materforge/data/materials/Al.yaml
print(path.read_text())   # the raw YAML

An unknown name raises ValueError and lists what is available:

get_material_path('inconel')
# ValueError: Unknown material 'inconel'. Available materials: 1.4301, Al, Al2O3

Next Steps