Material Base Class

Overview

The Material class serves as the base class for all materials in BurnMan, including Mineral Classes (Mineral), Solutions (Solution), and Composite Class (Composite). It defines the common interface through which all thermodynamic and elastic properties are computed, as well as the workflow for setting state variables and selecting thermodynamic models.

Subclasses implement the specific physical behaviour (equations of state, solution models, mechanical mixing laws), while Material ensures that all materials (simple or composite) expose a consistent and unified interface.

Regardless of type, materials support the same set of state variables and property queries.

Typical usage follows this pattern:

1. Instantiate a material object.

2. Set the state using one or more of:

   • Material.set_state() — set pressure and temperature,

   • Material.number_of_moles — specify the material amount.

3. Query thermodynamic properties, such as density, heat capacities, expansivity, elastic parameters, or seismic velocities.

Thermodynamic properties are computed on demand, with caching to optimise performance. Changing any state variable automatically resets cached values to ensure consistency.

Property Evaluation

A large number of physical properties can be evaluated. Examples include:

• Pressure (pressure)

• Temperature (temperature)

• Number of moles (number_of_moles)

• Mass (mass)

• Gibbs energy (gibbs)

• Helmholtz energy (helmholtz)

• Enthalpy (enthalpy)

• Internal energy (internal_energy)

• Entropy (entropy)

• Density (density)

• Volume (volume) and molar volume (molar_volume)

• Heat capacities (molar_heat_capacity_p and molar_heat_capacity_v)

• Thermal expansivity (thermal_expansivity)

• Gruneisen parameter (gruneisen_parameter)

• Isothermal bulk modulus (Reuss) (isothermal_bulk_modulus_reuss)

• Isentropic bulk modulus (Reuss) (isentropic_bulk_modulus_reuss)

• Corresponding compressibilities (isothermal_compressibility_reuss, isentropic_compressibility_reuss)

• Shear modulus (shear_modulus)

• Effective seismic bulk and shear moduli (effective_isentropic_bulk_modulus, effective_shear_modulus), see Averaging Schemes.

• Seismic velocities (p_wave_velocity, shear_wave_velocity, bulk_sound_velocity), see Averaging Schemes.

Molar quantities are available via molar_-prefixed properties. Aliases exist for common properties (e.g., C_p for heat_capacity_p).

Properties generally require that the state (pressure and temperature) has been set before computation.

State Management

Material.set_state(pressure, temperature)

Sets the thermodynamic state of the material by updating its pressure (Pa) and temperature (K).

Material.set_state_with_volume(volume, temperature)

Sets the state of the material using volume (\(\mathrm{m}^3\)) rather than pressure (Pa). The method internally performs a pressure inversion: it solves for the pressure that produces the specified volume at the given temperature.

Introspection and Debugging

Material.to_string()

Returns a human-readable string describing the material. Subclasses typically override this to include formula, composition, or model information.

Material.debug_print()

Prints detailed diagnostic information about the material, including its current state, cached properties, and any internal solver or model details relevant to the subclass. Intended primarily for debugging complex materials such as solutions or composites.

Material.unroll()

Expands the material into a flat list of burnman.Mineral objects and their molar fractions.

Material.print_minerals_of_current_state()

Prints a formatted list of all constituent minerals after applying the current pressure, temperature, and composition. This method invokes the same internal expansion logic as Material.unroll() and is useful for inspecting the active mineral assemblage within solutions or composites.

Evaluation Routines

Material.evaluate(property_list, pressures, temperatures, molar_fractions=None)

Computes and returns a thermodynamic property or properties at the requested conditions. The list of properties should be provided as a list of strings in property_list. The conditions are specified via arrays which may be of arbitrary shape, with broadcasting applied as needed. Pressure and temperature arrays must have the same shape.

Material.evaluate_with_volumes(property_name, volumes, temperatures, molar_fractions=None)

Evaluates a specified property using externally supplied volume values rather than pressures. This method performs a pressure inversion internally to determine the corresponding pressures for the given volumes at the specified temperatures.