belfem::MaterialFactory Class Reference

Factory class for creating material objects and associated property functions. More...

#include <cl_MaterialFactory.hpp>

Public Types
enum class	BuiltinKind { Iron , OtherKnown , Unknown }

Public Member Functions
	MaterialFactory ()=default
	MaterialFactory (const input::Section *aSection, const bool aBuildTables=true)
	Build every material a 'materials' deck section defines.
	~MaterialFactory ()=default
Material *	create_material (const string &aLabel, const real aRRR=BELFEM_QUIET_NAN, const bool aBuildTables=true)
	Create a material by label.
void	print_material_list (std::ostream &aStream)
Material *	create_material (const string &aLibraryPath, const string &aLabel)
	Create a user-defined material from shared library.
Map< string, Material * > &	materials ()
material::BhCurve *	create_bh_curve (const string &aPath, const string &aLabel)
	Create a B-H curve from file for ferromagnetic materials.
material::JcFunction *	create_jc_function (const real aJc0, const real aB, const real aBc, const real aK)
	Create a Jc function using the modified Kim analytical model.
material::JcFunction *	create_jc_function (const string &aPath, const string &aLabel)
	Create a Jc (or n) function from database file.
void	check_unused_input (const input::Section *aSection, const string &aLabel, const string &aShape, const Cell< string > &aKeys, const Cell< string > &aSections)
	refuse any key or subsection the resolved material shape does not read

Static Public Member Functions
static BuiltinKind	builtin_kind (const string &aName)
	Classify a builtin name the way create_material() resolves it.
static bool	curve_tolerates_builtin (const string &aValue)
	Whether a 'builtin' value may stand beside a b-h curve.
static bool	is_pure_metal_label (const string &aLabel)
	Whether a name is an alias of a builtin pure metal.

Detailed Description

Factory class for creating material objects and associated property functions.

The MaterialFactory provides a centralized interface for creating:

• Material objects (Copper, Silver, YBCO, etc.)
• B-H curves for ferromagnetic materials
• Critical current density (Jc) functions for superconductors
• Power law exponent (n) functions for superconductors

IMPORTANT USAGE NOTES:

1. OWNERSHIP: When you assign a B-H curve, Jc function, or n function to a material using set_bh_curve(), set_jc_function(), or set_n_function(), the material takes OWNERSHIP and will delete the object in its destructor. DO NOT manually delete these objects after assignment.
2. MANUAL ASSIGNMENT with the create_*() methods: they only create the object; call the material's load_bh_curve() / set_jc_function() / set_n_function() yourself. The input-section constructor does this wiring for you.
3. CONSTANT PROPERTIES: If Jc or n are constant values, no function object should be created. Instead, the constant value is stored directly in the material class. Only create functions when properties vary with field, angle, or temperature.

Example usage:

MaterialFactory factory;
 
// Create a copper material
Material* copper = factory.create_material("copper");
copper->set_RRR(2000);
 
// Create HTS with Jc function
Material* ybco = factory.create_material("YBCO");
material::JcFunction* jc = factory.create_jc_function(1e9, 5.0, 0.5, 2.0);
ybco->set_jc_function(jc);  // YBCO now owns jc, will delete it
 
// Create ferromagnetic material with B-H curve
Material* ferro = factory.create_material("SomeFerro");
material::BhCurve* bh = factory.create_bh_curve("bhdata.txt", "Ferro");
ferro->load_bh_curve(bh);  // Ferro now owns bh and routes mu/H/dmudH through it
                           // ( set_bh_curve() alone only stores the pointer )

See also

BELFEM Materials Module - Usage Guide

Member Enumeration Documentation

BuiltinKind

enum class belfem::MaterialFactory::BuiltinKind

strong

Enumerator
Iron	an iron alias: iron, ferro, fe
OtherKnown	any other alias, or an alloy formula of pure metals
Unknown	a name create_material() cannot resolve to either

Constructor & Destructor Documentation

MaterialFactory() [1/2]

belfem::MaterialFactory::MaterialFactory ( )

default

MaterialFactory() [2/2]

belfem::MaterialFactory::MaterialFactory	(	const input::Section *	aSection,
		const bool	aBuildTables = true )

Build every material a 'materials' deck section defines.

Parameters

aSection	the 'materials' section of the input file
aBuildTables	build the rho database on construction; off writes no database to the cwd, the temperature splines are built either way

~MaterialFactory()

belfem::MaterialFactory::~MaterialFactory ( )

default

Member Function Documentation

builtin_kind()

MaterialFactory::BuiltinKind belfem::MaterialFactory::builtin_kind ( const string & aName )

static

Classify a builtin name the way create_material() resolves it.

Case-insensitive; builds no material. An alloy formula counts as known only if its to_pair() labels are at least one pure-metal alias and nothing but pure-metal aliases and the rrr token, so a nameplate such as aisi305 is Unknown even though create_material() would hand it to the Alloy constructor.

check_unused_input()

void belfem::MaterialFactory::check_unused_input	(	const input::Section *	aSection,
		const string &	aLabel,
		const string &	aShape,
		const Cell< string > &	aKeys,
		const Cell< string > &	aSections )

refuse any key or subsection the resolved material shape does not read

A material section selects exactly one shape – a b-h curve, a builtin, or a plugin – and each shape consumes a different set of keys. Everything else used to be dropped without a word, so a misspelled key, a key belonging to another shape, or a constant that lost to a file all behaved as if the deck had never mentioned them.

This is an ALLOW-LIST rather than a record of what happened to be read, because the two are not the same predicate: RRR on a ybco IS read here and then dropped by the constructor, so only an explicit per-shape contract catches it.

Parameters

aSection	the material section, or one of its subsections
aLabel	material name, for the error message
aShape	shape name, for the error message
aKeys	keys this shape reads
aSections	subsection types this shape enters

create_bh_curve()

material::BhCurve * belfem::MaterialFactory::create_bh_curve	(	const string &	aPath,
		const string &	aLabel )

Create a B-H curve from file for ferromagnetic materials.

Creates a B-H curve object by loading data from a file. This curve defines the relationship between magnetic flux density (B) and magnetic field strength (H) for ferromagnetic materials.

IMPORTANT: This function only CREATES the B-H curve. You must manually assign it to a material using material->load_bh_curve(). Once assigned, the material takes ownership and will delete the curve.

Parameters

aPath	Path to the B-H curve data file, resolved through material::data_file(): the run directory first, then $BELFEM_DATA/material
aLabel	Identifier label for this B-H curve

Returns

Pointer to created B-H curve (ownership transfers to material upon assignment)

Example:

MaterialFactory factory;
Material* ferro = factory.create_material("SomeFerro");
 
// Create B-H curve
material::BhCurve* bh = factory.create_bh_curve("iron_bh.dat", "Iron");
 
// Assign to material (material now owns bh and uses it for mu/H)
ferro->load_bh_curve(bh);

create_jc_function() [1/2]

material::JcFunction * belfem::MaterialFactory::create_jc_function	(	const real	aJc0,
		const real	aB,
		const real	aBc,
		const real	aK )

Create a Jc function using the modified Kim analytical model.

Creates a critical current density function for superconductors using the modified Kim model. This is an analytical model suitable for quick calculations when experimental data is not available.

The modified Kim model expresses Jc as a function of magnetic field.

IMPORTANT: This function only CREATES the Jc function. You must manually assign it to a material using material->set_jc_function() or material->set_n_function(). Once assigned, the material takes ownership and will delete the function.

Parameters

aJc0	Critical current density at zero field [A/m²]
aB	Characteristic field scale B0 [T]
aBc	Anisotropy parameter k² (dimensionless)
aK	Field-dependence exponent α (dimensionless)

Returns

Pointer to created Jc function (ownership transfers to material upon assignment)

Example:

MaterialFactory factory;
Material* ybco = factory.create_material("YBCO");
 
// Create Jc function using modified Kim model
real jc0 = 1e9;    // A/m²
real B0 = 5.0;     // T
real k2 = 0.5;     // anisotropy k², dimensionless
real alpha = 2.0;  // exponent
material::JcFunction* jc = factory.create_jc_function(jc0, B0, k2, alpha);
 
// Assign to material (material now owns jc)
ybco->set_jc_function(jc);

create_jc_function() [2/2]

material::JcFunction * belfem::MaterialFactory::create_jc_function	(	const string &	aPath,
		const string &	aLabel )

Create a Jc (or n) function from database file.

Creates a critical current density function (or power law exponent function) by loading experimental data from a file. This provides more accurate results than analytical models when experimental data is available.

The function can represent:

• Jc(B, angle, T) : Critical current density
• n(B, angle, T) : Power law exponent

IMPORTANT: This function only CREATES the function object. You must manually assign it to a material using material->set_jc_function() or material->set_n_function(). Once assigned, the material takes ownership and will delete the function.

NOTE: If Jc or n are constant, do NOT create a function. Instead, store the constant value directly in the material using set_constant().

Parameters

aPath	Path to the database file containing Jc or n data, resolved through material::data_file(): the run directory first, then $BELFEM_DATA/material
aLabel	Identifier label for this function

Returns

Pointer to created function (ownership transfers to material upon assignment)

Example:

MaterialFactory factory;
Material* ybco = factory.create_material("YBCO");
 
// Create Jc function from database
material::JcFunction* jc = factory.create_jc_function("ybco.hdf5", "jc");
ybco->set_jc_function(jc);  // YBCO now owns jc
 
// Create n function from database
material::JcFunction* n = factory.create_jc_function("ybco.hdf5", "n");
ybco->set_n_function(n);    // YBCO now owns n

create_material() [1/2]

Material * belfem::MaterialFactory::create_material	(	const string &	aLabel,
		const real	aRRR = BELFEM_QUIET_NAN,
		const bool	aBuildTables = true )

Create a material by label.

Creates a material object from a predefined material database. The label is case-insensitive.

Currently supported labels ( aliases in parentheses ):

• aluminum (aluminium, al), chromium (cr), iron (ferro, fe), nickel (ni), copper (cu), silver (ag), indium (in), tin (sn), lead (pb) : PureMetal
• hastelloyc276 (hastelloy) : Hastelloy C-276 nickel alloy (LookupAlloy)
• ybco : YBCO high-temperature superconductor (HTS)
• magnesia (mgo, buffer) : NonMetal
• solder compositions of the form <Element><percentage>..., e.g. Sn40Pb60 : class Alloy ( typed PureMetal ) See print_material_list().

Parameters

aLabel	Material label (case-insensitive)
aRRR	Residual resistivity ratio; NaN keeps the material default
aBuildTables	Build the property lookup tables on construction

Returns

Pointer to created material (caller owns the material)

Exceptions

Error

if material label is not recognized

Example:

MaterialFactory factory;
Material* cu = factory.create_material("copper");
Material* ag = factory.create_material("SILVER");  // case-insensitive

create_material() [2/2]

Material * belfem::MaterialFactory::create_material	(	const string &	aLibraryPath,
		const string &	aLabel )

Create a user-defined material from shared library.

Loads a user-defined material from an external shared library (.so, .dylib, .dll). The library must contain an initialization function with the signature:

extern "C" void \<aLabel\>_init(Material* mat);

Within the init function, users define material properties using:

• mat->set_constant() - For constant values
• mat->set_user_defined_function() - For custom functions
• mat->set_user_defined_polynomial() - For polynomial functions
• mat->set_jc_function() / mat->set_n_function() - For superconductor properties

Parameters

aLibraryPath	Path to shared library file
aLabel	Material label (must match the init function name: <aLabel>_init)

Returns

Pointer to created user-defined material (caller owns the material)

Exceptions

Error

if library cannot be loaded or init function not found

Example user library (myalloy.cpp):

#include "cl_Material.hpp"
using namespace belfem;
 
real my_rho(const Material* mat, real T) {
    return 1.7e-8 * (1.0 + 0.004 * (T - 293.0));
}
 
extern "C" void MyAlloy_init(Material* mat) {
    mat->set_constant(MaterialProperty::E, 200e9);
    mat->set_constant(MaterialProperty::nu, 0.3);
    mat->set_user_defined_function(MaterialProperty::rho,
                                    MaterialDependency::T,
                                    &my_rho);
    // cp(T) = 0.12*T + 385  (descending order: T¹, T⁰)
    std::vector<real> cp_coeffs = {0.12, 385.0};
    mat->set_user_defined_polynomial(MaterialProperty::cp, cp_coeffs);
}

Compile: g++ -shared -fPIC myalloy.cpp -o libmyalloy.so -I/path/to/belfem/include

The library path is resolved through material::data_file(): the run directory first, then $BELFEM_DATA/material. A name that matches nothing is still passed to dlopen, which searches $LD_LIBRARY_PATH.

Usage:

MaterialFactory factory;
Material* mat = factory.create_material("libmyalloy.so", "MyAlloy");

curve_tolerates_builtin()

bool belfem::MaterialFactory::curve_tolerates_builtin ( const string & aValue )

static

Whether a 'builtin' value may stand beside a b-h curve.

Case-insensitive; builds no material. The valueless marker ( stored as "true" ), an iron alias, or a name the factory does not know pass; a known non-iron builtin or a formula of known pure metals is refused, since the curve always builds an iron.

is_pure_metal_label()

bool belfem::MaterialFactory::is_pure_metal_label ( const string & aLabel )

static

Whether a name is an alias of a builtin pure metal.

Case-insensitive; builds no material. An alloy formula is not a pure metal, even though create_material() types it PureMetal.

materials()

Map< string, Material * > & belfem::MaterialFactory::materials ( )

inline

print_material_list()

void belfem::MaterialFactory::print_material_list

(

std::ostream &

aStream

)

---

The documentation for this class was generated from the following files:

• src/physics/materials/cl_MaterialFactory.hpp
• src/physics/materials/cl_MaterialFactory.cpp