belfem::MaterialFactory Class Reference

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

#include <cl_MaterialFactory.hpp>

Public Member Functions
	MaterialFactory ()=default
	Default constructor.
	MaterialFactory (const input::Section *aSection)
	Constructor with input section.
	~MaterialFactory ()=default
	Default destructor.
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

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

Constructor & Destructor Documentation

MaterialFactory() [1/2]

belfem::MaterialFactory::MaterialFactory ( )

default

Default constructor.

MaterialFactory() [2/2]

belfem::MaterialFactory::MaterialFactory

(

const input::Section *

aSection

)

Constructor with input section.

~MaterialFactory()

belfem::MaterialFactory::~MaterialFactory ( )

default

Default destructor.

Member Function Documentation

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");

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