Physics Equation Templates

Reusable materials-physics equation templates for physics-informed GPR mean functions.

matgpr.physics_equations

PhysicsFeatureSpec dataclass

Metadata for one canonical physics-equation input feature.

Source code in matgpr/physics_equations.py

@dataclass(frozen=True)
class PhysicsFeatureSpec:
    """Metadata for one canonical physics-equation input feature."""

    name: str
    description: str = ""
    units: str | None = None
    required: bool = True

    def __post_init__(self) -> None:
        if not str(self.name).strip():
            raise ValueError("feature spec name must be non-empty")
        object.__setattr__(self, "name", str(self.name))
        object.__setattr__(self, "description", str(self.description))

    def to_dict(self) -> dict[str, object]:
        """Return a serializable feature metadata record."""
        return {
            "name": self.name,
            "description": self.description,
            "units": self.units,
            "required": self.required,
        }

to_dict()

Return a serializable feature metadata record.

Source code in matgpr/physics_equations.py

def to_dict(self) -> dict[str, object]:
    """Return a serializable feature metadata record."""
    return {
        "name": self.name,
        "description": self.description,
        "units": self.units,
        "required": self.required,
    }

PhysicsParameterSpec dataclass

Metadata for one physics-equation parameter.

Source code in matgpr/physics_equations.py

@dataclass(frozen=True)
class PhysicsParameterSpec:
    """Metadata for one physics-equation parameter."""

    name: str
    kind: str
    default_value: float | None = None
    description: str = ""
    units: str | None = None
    positive: bool = False
    learned_on_fit: bool = False

    def __post_init__(self) -> None:
        if not str(self.name).strip():
            raise ValueError("parameter spec name must be non-empty")
        if self.kind not in {"learnable", "fixed"}:
            raise ValueError("parameter spec kind must be 'learnable' or 'fixed'")
        object.__setattr__(self, "name", str(self.name))
        object.__setattr__(self, "description", str(self.description))

    def to_dict(self) -> dict[str, object]:
        """Return a serializable parameter metadata record."""
        return {
            "name": self.name,
            "kind": self.kind,
            "default_value": self.default_value,
            "description": self.description,
            "units": self.units,
            "positive": self.positive,
            "learned_on_fit": self.learned_on_fit,
        }

to_dict()

Return a serializable parameter metadata record.

Source code in matgpr/physics_equations.py

def to_dict(self) -> dict[str, object]:
    """Return a serializable parameter metadata record."""
    return {
        "name": self.name,
        "kind": self.kind,
        "default_value": self.default_value,
        "description": self.description,
        "units": self.units,
        "positive": self.positive,
        "learned_on_fit": self.learned_on_fit,
    }

PhysicsEquationTemplate dataclass

Reusable physics-equation metadata for physics-informed GPR.

A template stores the equation callable plus the features, default learnable-parameter initial values, fixed constants, sign constraints, and documentation needed to use the equation as a :class:matgpr.PhysicsInformedMean.

Source code in matgpr/physics_equations.py

@dataclass(frozen=True)
class PhysicsEquationTemplate:
    """Reusable physics-equation metadata for physics-informed GPR.

    A template stores the equation callable plus the features, default
    learnable-parameter initial values, fixed constants, sign constraints, and
    documentation needed to use the equation as a
    :class:`matgpr.PhysicsInformedMean`.
    """

    name: str
    equation: PhysicsEquation
    feature_names: Sequence[str]
    default_learnable_parameters: Mapping[str, float] = field(default_factory=dict)
    positive_parameters: Sequence[str] = ()
    default_fixed_parameters: Mapping[str, float] = field(default_factory=dict)
    aliases: Sequence[str] = ()
    category: str = ""
    description: str = ""
    equation_latex: str = ""
    target_description: str = ""
    target_units: str | None = None
    feature_descriptions: Mapping[str, str] = field(default_factory=dict)
    feature_units: Mapping[str, str] = field(default_factory=dict)
    parameter_descriptions: Mapping[str, str] = field(default_factory=dict)
    parameter_units: Mapping[str, str] = field(default_factory=dict)
    applications: Sequence[str] = ()
    assumptions: Sequence[str] = ()
    notes: Sequence[str] = ()
    references: Sequence[str] = ()
    tags: Sequence[str] = ()

    def __post_init__(self) -> None:
        if not self.name:
            raise ValueError("name must be non-empty")
        if not self.feature_names:
            raise ValueError("feature_names must contain at least one feature")

        object.__setattr__(self, "feature_names", tuple(self.feature_names))
        object.__setattr__(self, "positive_parameters", tuple(self.positive_parameters))
        object.__setattr__(self, "aliases", tuple(self.aliases))
        object.__setattr__(self, "applications", tuple(self.applications))
        object.__setattr__(self, "assumptions", tuple(self.assumptions))
        object.__setattr__(self, "notes", tuple(self.notes))
        object.__setattr__(self, "references", tuple(self.references))
        object.__setattr__(self, "tags", tuple(self.tags))
        object.__setattr__(
            self,
            "default_learnable_parameters",
            _validate_numeric_mapping(
                self.default_learnable_parameters,
                "default_learnable_parameters",
            ),
        )
        object.__setattr__(
            self,
            "default_fixed_parameters",
            _validate_numeric_mapping(self.default_fixed_parameters, "default_fixed_parameters"),
        )
        object.__setattr__(
            self,
            "feature_descriptions",
            dict(self.feature_descriptions),
        )
        object.__setattr__(self, "feature_units", dict(self.feature_units))
        object.__setattr__(
            self,
            "parameter_descriptions",
            dict(self.parameter_descriptions),
        )
        object.__setattr__(self, "parameter_units", dict(self.parameter_units))

        missing_positive = set(self.positive_parameters).difference(
            self.default_learnable_parameters
        )
        if missing_positive:
            raise ValueError(
                "positive_parameters must refer to default learnable parameters; "
                f"unknown names: {sorted(missing_positive)}"
            )

    @property
    def required_features(self) -> tuple[str, ...]:
        """Feature names expected by the equation callable."""
        return tuple(self.feature_names)

    @property
    def learnable_parameter_names(self) -> tuple[str, ...]:
        """Default parameter names optimized jointly with the GP."""
        return tuple(self.default_learnable_parameters)

    @property
    def fixed_parameter_names(self) -> tuple[str, ...]:
        """Default fixed-constant names passed to the equation."""
        return tuple(self.default_fixed_parameters)

    def feature_specs(self) -> tuple[PhysicsFeatureSpec, ...]:
        """Return report-ready metadata for the required input features."""
        return tuple(
            PhysicsFeatureSpec(
                name=feature,
                description=self.feature_descriptions.get(feature, ""),
                units=self.feature_units.get(feature),
                required=True,
            )
            for feature in self.feature_names
        )

    def parameter_specs(self) -> tuple[PhysicsParameterSpec, ...]:
        """Return report-ready metadata for learned and fixed parameters."""
        learnable = tuple(
            PhysicsParameterSpec(
                name=name,
                kind="learnable",
                default_value=value,
                description=self.parameter_descriptions.get(name, ""),
                units=self.parameter_units.get(name),
                positive=name in self.positive_parameters,
                learned_on_fit=True,
            )
            for name, value in self.default_learnable_parameters.items()
        )
        fixed = tuple(
            PhysicsParameterSpec(
                name=name,
                kind="fixed",
                default_value=value,
                description=self.parameter_descriptions.get(name, ""),
                units=self.parameter_units.get(name),
                positive=False,
                learned_on_fit=False,
            )
            for name, value in self.default_fixed_parameters.items()
        )
        return (*learnable, *fixed)

    def build_mean_function(
        self,
        feature_indices: Mapping[str, int],
        *,
        learnable_parameter_overrides: Mapping[str, float] | None = None,
        fixed_parameter_overrides: Mapping[str, float] | None = None,
        positive_parameters: Sequence[str] | None = None,
        feature_means: Mapping[str, float] | None = None,
        feature_stds: Mapping[str, float] | None = None,
        target_mean: float = 0.0,
        target_std: float = 1.0,
        strict_features: bool = True,
    ) -> PhysicsInformedMean:
        """Build a :class:`matgpr.PhysicsInformedMean` from this template.

        Parameters
        ----------
        feature_indices
            Mapping from template feature names to columns in the model feature
            matrix. Keys use the template's canonical feature names even if the
            original dataframe columns have different names.
        learnable_parameter_overrides
            Optional initial values that replace selected template defaults.
        fixed_parameter_overrides
            Optional fixed constants that replace selected template defaults.
        positive_parameters
            Optional replacement for the template positive-parameter list.
        feature_means, feature_stds
            Optional scaling metadata so the physics equation receives original
            physical units when the GPR feature matrix is standardized.
        target_mean, target_std
            Target standardization metadata passed to ``PhysicsInformedMean``.
        strict_features
            If ``True``, require ``feature_indices`` to include every template
            feature.
        """
        resolved_feature_indices = dict(feature_indices)
        if strict_features:
            missing = [
                feature for feature in self.feature_names if feature not in resolved_feature_indices
            ]
            if missing:
                raise ValueError(f"feature_indices is missing template features: {missing}")

        learnable_parameters = dict(self.default_learnable_parameters)
        if learnable_parameter_overrides is not None:
            learnable_parameters.update(
                _validate_numeric_mapping(
                    learnable_parameter_overrides,
                    "learnable_parameter_overrides",
                )
            )

        fixed_parameters = dict(self.default_fixed_parameters)
        if fixed_parameter_overrides is not None:
            fixed_parameters.update(
                _validate_numeric_mapping(
                    fixed_parameter_overrides,
                    "fixed_parameter_overrides",
                )
            )

        positive = (
            tuple(self.positive_parameters)
            if positive_parameters is None
            else tuple(positive_parameters)
        )

        return PhysicsInformedMean(
            equation=self.equation,
            feature_indices=resolved_feature_indices,
            learnable_parameters=learnable_parameters,
            positive_parameters=positive,
            fixed_parameters=fixed_parameters,
            feature_means=feature_means,
            feature_stds=feature_stds,
            target_mean=target_mean,
            target_std=target_std,
        )

    def summary(self) -> dict[str, object]:
        """Return a compact serializable summary for reports."""
        return {
            "name": self.name,
            "aliases": list(self.aliases),
            "category": self.category,
            "features": list(self.feature_names),
            "learnable_parameters": dict(self.default_learnable_parameters),
            "positive_parameters": list(self.positive_parameters),
            "fixed_parameters": dict(self.default_fixed_parameters),
            "description": self.description,
            "equation_latex": self.equation_latex,
            "applications": list(self.applications),
            "assumptions": list(self.assumptions),
            "tags": list(self.tags),
        }

    def discovery_record(self) -> dict[str, object]:
        """Return complete metadata for registry/discovery workflows."""
        return {
            **self.summary(),
            "target_description": self.target_description,
            "target_units": self.target_units,
            "feature_metadata": [spec.to_dict() for spec in self.feature_specs()],
            "parameter_metadata": [spec.to_dict() for spec in self.parameter_specs()],
            "notes": list(self.notes),
            "references": list(self.references),
        }

required_features property

Feature names expected by the equation callable.

learnable_parameter_names property

Default parameter names optimized jointly with the GP.

fixed_parameter_names property

Default fixed-constant names passed to the equation.

feature_specs()

Return report-ready metadata for the required input features.

Source code in matgpr/physics_equations.py

def feature_specs(self) -> tuple[PhysicsFeatureSpec, ...]:
    """Return report-ready metadata for the required input features."""
    return tuple(
        PhysicsFeatureSpec(
            name=feature,
            description=self.feature_descriptions.get(feature, ""),
            units=self.feature_units.get(feature),
            required=True,
        )
        for feature in self.feature_names
    )

parameter_specs()

Return report-ready metadata for learned and fixed parameters.

Source code in matgpr/physics_equations.py

def parameter_specs(self) -> tuple[PhysicsParameterSpec, ...]:
    """Return report-ready metadata for learned and fixed parameters."""
    learnable = tuple(
        PhysicsParameterSpec(
            name=name,
            kind="learnable",
            default_value=value,
            description=self.parameter_descriptions.get(name, ""),
            units=self.parameter_units.get(name),
            positive=name in self.positive_parameters,
            learned_on_fit=True,
        )
        for name, value in self.default_learnable_parameters.items()
    )
    fixed = tuple(
        PhysicsParameterSpec(
            name=name,
            kind="fixed",
            default_value=value,
            description=self.parameter_descriptions.get(name, ""),
            units=self.parameter_units.get(name),
            positive=False,
            learned_on_fit=False,
        )
        for name, value in self.default_fixed_parameters.items()
    )
    return (*learnable, *fixed)

build_mean_function(feature_indices, *, learnable_parameter_overrides=None, fixed_parameter_overrides=None, positive_parameters=None, feature_means=None, feature_stds=None, target_mean=0.0, target_std=1.0, strict_features=True)

Build a :class:matgpr.PhysicsInformedMean from this template.

Parameters:

Name	Type	Description	Default
feature_indices	Mapping[str, int]	Mapping from template feature names to columns in the model feature matrix. Keys use the template's canonical feature names even if the original dataframe columns have different names.	required
learnable_parameter_overrides	Mapping[str, float] | None	Optional initial values that replace selected template defaults.	None
fixed_parameter_overrides	Mapping[str, float] | None	Optional fixed constants that replace selected template defaults.	None
positive_parameters	Sequence[str] | None	Optional replacement for the template positive-parameter list.	None
feature_means	Mapping[str, float] | None	Optional scaling metadata so the physics equation receives original physical units when the GPR feature matrix is standardized.	None
feature_stds	Mapping[str, float] | None	Optional scaling metadata so the physics equation receives original physical units when the GPR feature matrix is standardized.	None
target_mean	float	Target standardization metadata passed to PhysicsInformedMean.	0.0
target_std	float	Target standardization metadata passed to PhysicsInformedMean.	0.0
strict_features	bool	If True, require feature_indices to include every template feature.	True

Source code in matgpr/physics_equations.py

def build_mean_function(
    self,
    feature_indices: Mapping[str, int],
    *,
    learnable_parameter_overrides: Mapping[str, float] | None = None,
    fixed_parameter_overrides: Mapping[str, float] | None = None,
    positive_parameters: Sequence[str] | None = None,
    feature_means: Mapping[str, float] | None = None,
    feature_stds: Mapping[str, float] | None = None,
    target_mean: float = 0.0,
    target_std: float = 1.0,
    strict_features: bool = True,
) -> PhysicsInformedMean:
    """Build a :class:`matgpr.PhysicsInformedMean` from this template.

    Parameters
    ----------
    feature_indices
        Mapping from template feature names to columns in the model feature
        matrix. Keys use the template's canonical feature names even if the
        original dataframe columns have different names.
    learnable_parameter_overrides
        Optional initial values that replace selected template defaults.
    fixed_parameter_overrides
        Optional fixed constants that replace selected template defaults.
    positive_parameters
        Optional replacement for the template positive-parameter list.
    feature_means, feature_stds
        Optional scaling metadata so the physics equation receives original
        physical units when the GPR feature matrix is standardized.
    target_mean, target_std
        Target standardization metadata passed to ``PhysicsInformedMean``.
    strict_features
        If ``True``, require ``feature_indices`` to include every template
        feature.
    """
    resolved_feature_indices = dict(feature_indices)
    if strict_features:
        missing = [
            feature for feature in self.feature_names if feature not in resolved_feature_indices
        ]
        if missing:
            raise ValueError(f"feature_indices is missing template features: {missing}")

    learnable_parameters = dict(self.default_learnable_parameters)
    if learnable_parameter_overrides is not None:
        learnable_parameters.update(
            _validate_numeric_mapping(
                learnable_parameter_overrides,
                "learnable_parameter_overrides",
            )
        )

    fixed_parameters = dict(self.default_fixed_parameters)
    if fixed_parameter_overrides is not None:
        fixed_parameters.update(
            _validate_numeric_mapping(
                fixed_parameter_overrides,
                "fixed_parameter_overrides",
            )
        )

    positive = (
        tuple(self.positive_parameters)
        if positive_parameters is None
        else tuple(positive_parameters)
    )

    return PhysicsInformedMean(
        equation=self.equation,
        feature_indices=resolved_feature_indices,
        learnable_parameters=learnable_parameters,
        positive_parameters=positive,
        fixed_parameters=fixed_parameters,
        feature_means=feature_means,
        feature_stds=feature_stds,
        target_mean=target_mean,
        target_std=target_std,
    )

summary()

Return a compact serializable summary for reports.

Source code in matgpr/physics_equations.py

def summary(self) -> dict[str, object]:
    """Return a compact serializable summary for reports."""
    return {
        "name": self.name,
        "aliases": list(self.aliases),
        "category": self.category,
        "features": list(self.feature_names),
        "learnable_parameters": dict(self.default_learnable_parameters),
        "positive_parameters": list(self.positive_parameters),
        "fixed_parameters": dict(self.default_fixed_parameters),
        "description": self.description,
        "equation_latex": self.equation_latex,
        "applications": list(self.applications),
        "assumptions": list(self.assumptions),
        "tags": list(self.tags),
    }

discovery_record()

Return complete metadata for registry/discovery workflows.

Source code in matgpr/physics_equations.py

def discovery_record(self) -> dict[str, object]:
    """Return complete metadata for registry/discovery workflows."""
    return {
        **self.summary(),
        "target_description": self.target_description,
        "target_units": self.target_units,
        "feature_metadata": [spec.to_dict() for spec in self.feature_specs()],
        "parameter_metadata": [spec.to_dict() for spec in self.parameter_specs()],
        "notes": list(self.notes),
        "references": list(self.references),
    }

arrhenius_rate_equation(features, parameters)

Temperature-activated Arrhenius response.

The equation is A exp(-E_a / (R T)). It is useful for transport, reaction, diffusion, conductivity, and rate-like material properties when temperature is an important control variable.

Source code in matgpr/physics_equations.py

def arrhenius_rate_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Temperature-activated Arrhenius response.

    The equation is ``A exp(-E_a / (R T))``. It is useful for transport,
    reaction, diffusion, conductivity, and rate-like material properties when
    temperature is an important control variable.
    """
    temperature = _positive_feature(features, "temperature_k")
    prefactor = _parameter(parameters, "prefactor", reference=temperature)
    activation_energy = _parameter(parameters, "activation_energy", reference=temperature)
    gas_constant = _parameter(
        parameters,
        "gas_constant",
        reference=temperature,
        default=R_GAS_CONSTANT_J_MOL_K,
    )
    denominator = torch.clamp(gas_constant * temperature, min=_tiny_like(temperature))
    return prefactor * torch.exp(-activation_energy / denominator)

arrhenius_sqrt_time_equation(features, parameters)

Parabolic-growth mean from Arrhenius rate and exposure time.

The equation is offset + sqrt(A exp(-E_a / (R T)) time). It is useful for oxidation, diffusion-depth, aging, and other square-root-time trends.

Source code in matgpr/physics_equations.py

def arrhenius_sqrt_time_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Parabolic-growth mean from Arrhenius rate and exposure time.

    The equation is ``offset + sqrt(A exp(-E_a / (R T)) time)``. It is useful
    for oxidation, diffusion-depth, aging, and other square-root-time trends.
    """
    time = _positive_feature(features, "time")
    offset = _parameter(parameters, "offset", reference=time, default=0.0)
    rate = arrhenius_rate_equation(features, parameters)
    return offset + torch.sqrt(torch.clamp(rate * time, min=0.0))

arrhenius_linear_growth_equation(features, parameters)

Linear-growth mean controlled by an Arrhenius rate.

The equation is offset + A exp(-E_a / (R T)) time. It is useful for reaction-controlled oxidation, aging, or damage accumulation when the response is approximately linear in time at fixed temperature.

Source code in matgpr/physics_equations.py

def arrhenius_linear_growth_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Linear-growth mean controlled by an Arrhenius rate.

    The equation is ``offset + A exp(-E_a / (R T)) time``. It is useful for
    reaction-controlled oxidation, aging, or damage accumulation when the
    response is approximately linear in time at fixed temperature.
    """
    time = _positive_feature(features, "time")
    offset = _parameter(parameters, "offset", reference=time, default=0.0)
    rate = arrhenius_rate_equation(features, parameters)
    return offset + rate * time

linear_growth_equation(features, parameters)

Linear growth with exposure time or another nonnegative driving variable.

The equation is offset + rate * time. It is useful for oxidation, aging, damage accumulation, or thickness/mass growth when a first-order time trend is an appropriate physics prior.

Source code in matgpr/physics_equations.py

def linear_growth_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Linear growth with exposure time or another nonnegative driving variable.

    The equation is ``offset + rate * time``. It is useful for oxidation,
    aging, damage accumulation, or thickness/mass growth when a first-order
    time trend is an appropriate physics prior.
    """
    time = _positive_feature(features, "time")
    rate = _parameter(parameters, "rate", reference=time)
    offset = _parameter(parameters, "offset", reference=time, default=0.0)
    return offset + rate * time

linear_parabolic_growth_equation(features, parameters)

Linear-parabolic growth from mixed interface and diffusion control.

The equation solves m(t)^2 + linear_rate * m(t) = parabolic_rate * time for the nonnegative root and adds an optional offset. It is useful for oxidation or other growth processes that transition smoothly between interface-controlled and diffusion-controlled kinetics.

Source code in matgpr/physics_equations.py

def linear_parabolic_growth_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Linear-parabolic growth from mixed interface and diffusion control.

    The equation solves ``m(t)^2 + linear_rate * m(t) = parabolic_rate * time``
    for the nonnegative root and adds an optional ``offset``. It is useful for
    oxidation or other growth processes that transition smoothly between
    interface-controlled and diffusion-controlled kinetics.
    """
    time = _positive_feature(features, "time")
    linear_rate = _parameter(parameters, "linear_rate", reference=time)
    parabolic_rate = _parameter(parameters, "parabolic_rate", reference=time)
    offset = _parameter(parameters, "offset", reference=time, default=0.0)
    discriminant = linear_rate**2 + 4.0 * parabolic_rate * time
    growth = 0.5 * (torch.sqrt(torch.clamp(discriminant, min=0.0)) - linear_rate)
    return offset + growth

power_law_equation(features, parameters)

Power-law scaling with a single driving variable.

The equation is offset + coefficient * driving_variable ** exponent. It is a compact template for load effects, rate effects, and empirical scaling laws where a log-log trend is expected.

Source code in matgpr/physics_equations.py

def power_law_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Power-law scaling with a single driving variable.

    The equation is ``offset + coefficient * driving_variable ** exponent``.
    It is a compact template for load effects, rate effects, and empirical
    scaling laws where a log-log trend is expected.
    """
    driving_variable = _positive_feature(features, "driving_variable")
    coefficient = _parameter(parameters, "coefficient", reference=driving_variable)
    exponent = _parameter(parameters, "exponent", reference=driving_variable)
    offset = _parameter(parameters, "offset", reference=driving_variable, default=0.0)
    return offset + coefficient * torch.pow(driving_variable, exponent)

hall_petch_equation(features, parameters)

Hall-Petch-style inverse-square-root grain-size trend.

The equation is intrinsic_property + coefficient / sqrt(grain_size). It is useful for strength, hardness, yield stress, or related properties when grain-size strengthening is physically plausible.

Source code in matgpr/physics_equations.py

def hall_petch_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Hall-Petch-style inverse-square-root grain-size trend.

    The equation is ``intrinsic_property + coefficient / sqrt(grain_size)``.
    It is useful for strength, hardness, yield stress, or related properties
    when grain-size strengthening is physically plausible.
    """
    grain_size = _positive_feature(features, "grain_size")
    intrinsic_property = _parameter(parameters, "intrinsic_property", reference=grain_size)
    coefficient = _parameter(parameters, "coefficient", reference=grain_size)
    return intrinsic_property + coefficient / torch.sqrt(grain_size)

free_volume_exponential_equation(features, parameters)

Free-volume exponential trend for polymer transport properties.

The equation is offset + prefactor * exp(-barrier / free_volume_fraction). It is useful for diffusion, permeability, and segmental-mobility trends in polymers when fractional free volume is available.

Source code in matgpr/physics_equations.py

def free_volume_exponential_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Free-volume exponential trend for polymer transport properties.

    The equation is ``offset + prefactor * exp(-barrier / free_volume_fraction)``.
    It is useful for diffusion, permeability, and segmental-mobility trends in
    polymers when fractional free volume is available.
    """
    free_volume_fraction = _positive_feature(features, "free_volume_fraction")
    prefactor = _parameter(parameters, "prefactor", reference=free_volume_fraction)
    barrier = _parameter(parameters, "barrier", reference=free_volume_fraction)
    offset = _parameter(parameters, "offset", reference=free_volume_fraction, default=0.0)
    return offset + prefactor * torch.exp(-barrier / free_volume_fraction)

rule_of_mixtures_equation(features, parameters)

Linear rule of mixtures with an optional interaction term.

The equation is (1 - phi) matrix_property + phi inclusion_property + interaction phi (1 - phi). It is useful for composite, alloy, blend, or mixture properties when phase fraction is known.

Source code in matgpr/physics_equations.py

def rule_of_mixtures_equation(
    features: Mapping[str, torch.Tensor],
    parameters: Mapping[str, torch.Tensor],
) -> torch.Tensor:
    """Linear rule of mixtures with an optional interaction term.

    The equation is ``(1 - phi) matrix_property + phi inclusion_property +
    interaction phi (1 - phi)``. It is useful for composite, alloy, blend, or
    mixture properties when phase fraction is known.
    """
    volume_fraction = torch.clamp(_feature(features, "volume_fraction"), min=0.0, max=1.0)
    matrix_property = _parameter(parameters, "matrix_property", reference=volume_fraction)
    inclusion_property = _parameter(parameters, "inclusion_property", reference=volume_fraction)
    interaction = _parameter(parameters, "interaction", reference=volume_fraction, default=0.0)
    return (
        (1.0 - volume_fraction) * matrix_property
        + volume_fraction * inclusion_property
        + interaction * volume_fraction * (1.0 - volume_fraction)
    )

list_physics_equation_templates()

Return the registered reusable physics equation templates.

Source code in matgpr/physics_equations.py

def list_physics_equation_templates() -> tuple[PhysicsEquationTemplate, ...]:
    """Return the registered reusable physics equation templates."""
    return _PHYSICS_EQUATION_TEMPLATES

available_physics_equation_templates(*, include_aliases=False)

Return available template names, optionally including aliases.

Source code in matgpr/physics_equations.py

def available_physics_equation_templates(*, include_aliases: bool = False) -> tuple[str, ...]:
    """Return available template names, optionally including aliases."""
    names = [template.name for template in _PHYSICS_EQUATION_TEMPLATES]
    if include_aliases:
        names.extend(
            alias for template in _PHYSICS_EQUATION_TEMPLATES for alias in template.aliases
        )
    return tuple(names)

get_physics_equation_template(name)

Return a physics-equation template by name or alias.

Source code in matgpr/physics_equations.py

def get_physics_equation_template(name: str) -> PhysicsEquationTemplate:
    """Return a physics-equation template by name or alias."""
    key = _normalize_template_name(name)
    lookup = _template_lookup()
    if key not in lookup:
        available = ", ".join(available_physics_equation_templates(include_aliases=True))
        raise ValueError(
            f"Unknown physics equation template '{name}'. Available templates: {available}"
        )
    return lookup[key]

describe_physics_equation_template(name)

Return complete registry metadata for one physics-equation template.

Source code in matgpr/physics_equations.py

def describe_physics_equation_template(name: str) -> dict[str, object]:
    """Return complete registry metadata for one physics-equation template."""
    return get_physics_equation_template(name).discovery_record()

search_physics_equation_templates(query=None, *, application=None, tag=None, required_features=None)

Search registered templates by text, application, tag, or features.

This searches the built-in, human-authored template registry. It does not automatically discover new equations from data.

Source code in matgpr/physics_equations.py

def search_physics_equation_templates(
    query: str | None = None,
    *,
    application: str | None = None,
    tag: str | None = None,
    required_features: Sequence[str] | None = None,
) -> tuple[PhysicsEquationTemplate, ...]:
    """Search registered templates by text, application, tag, or features.

    This searches the built-in, human-authored template registry. It does not
    automatically discover new equations from data.
    """
    required_feature_set = (
        {_normalize_template_name(feature) for feature in required_features}
        if required_features is not None
        else None
    )
    matches: list[PhysicsEquationTemplate] = []
    for template in _PHYSICS_EQUATION_TEMPLATES:
        if query is not None and _normalize_template_name(query) not in _template_search_text(
            template
        ):
            continue
        if application is not None and not _contains_normalized(
            template.applications,
            application,
        ):
            continue
        if tag is not None and _normalize_template_name(tag) not in {
            _normalize_template_name(item) for item in template.tags
        }:
            continue
        if required_feature_set is not None:
            template_feature_set = {
                _normalize_template_name(feature) for feature in template.feature_names
            }
            if not required_feature_set.issubset(template_feature_set):
                continue
        matches.append(template)
    return tuple(matches)

summarize_physics_equation_templates(*, include_aliases=True)

Return a dataframe summary of registered physics-equation templates.

Source code in matgpr/physics_equations.py

def summarize_physics_equation_templates(
    *,
    include_aliases: bool = True,
) -> pd.DataFrame:
    """Return a dataframe summary of registered physics-equation templates."""
    rows = []
    for template in _PHYSICS_EQUATION_TEMPLATES:
        rows.append(
            {
                "name": template.name,
                "aliases": ", ".join(template.aliases) if include_aliases else "",
                "category": template.category,
                "description": template.description,
                "equation_latex": template.equation_latex,
                "required_features": ", ".join(template.feature_names),
                "learnable_parameters": ", ".join(template.learnable_parameter_names),
                "fixed_parameters": ", ".join(template.fixed_parameter_names),
                "positive_parameters": ", ".join(template.positive_parameters),
                "applications": ", ".join(template.applications),
                "assumptions": " ".join(template.assumptions),
                "tags": ", ".join(template.tags),
            }
        )
    return pd.DataFrame(rows)