BaseProfile

class profiles.base.BaseProfile(**kwargs)

Abstract base class for constructing symbolic profile functions.

BaseProfile provides the infrastructure for defining parameterized, symbolic expressions that can be evaluated numerically with units. Subclasses define their behavior by specifying independent variables, parameters, and symbolic expressions. Additional derived profiles, such as gradients or potentials, can be attached via derived_profile().

This class integrates:

• SymPy for symbolic construction

• unyt for unit-aware parameter handling

• Automated symbolic setup and expression management via a custom metaclass

• Optional serialization to and from minimal dictionaries

• Dynamic construction of secondary (derived) profiles

Intended Usage

Subclasses must define the following:

• __VARIABLES__ : list of str Independent variables of the profile.

• __PARAMETERS__ : dict of str, default values Named parameters for the profile function. These are provided at instantiation with units.

• __function__ : abstractmethod Returns the symbolic expression as a SymPy object.

• __function_units__ : abstractmethod Returns the dimensional units of the profile output.

Additional customization is possible using:

• __IS_ABSTRACT__ : bool Prevents symbolic setup and registration for base or template classes.

• __REGISTER__ : bool Controls whether the class is added to the global profile registry.

• __SETUP_AT__ : “init” or “import” Controls when symbolic setup occurs.

• __DERIVED_BASE__ : type Specifies the base class for any derived profiles.

Derived Profiles

Developers can attach secondary symbolic profiles using the @derived_profile decorator. These are dynamically constructed as subclasses and accessed via get_derived_profile.

Example

class MyProfile(BaseProfile):
    __IS_ABSTRACT__ = False
    __VARIABLES__ = ["x"]
    __PARAMETERS__ = {"a": 1.0}

    def __function__(self, x, a):
        return a * x**2

    def __function_units__(self, x_unit, a_unit):
        return a_unit * x_unit**2

    @derived_profile()
    @classmethod
    def gradient(cls, x, a):
        def func(x, a):
            return 2 * a * x

        def units(x_unit, a_unit):
            return a_unit * x_unit

        return func, units, ["x"], {"a": 1.0}

Calling Behavior

Instances of a profile are callable using profile(*variables, units=None, no_units=False). This evaluates the profile’s numerical expression at the given coordinate values with proper unit handling:

• If input variables have attached units (e.g., unyt_quantity), units are extracted automatically.

• If input variables are scalars, unit-less evaluation is assumed.

• The units argument can be used to force the output to specific units (e.g., units="Msun/kpc**3").

• If no_units=True, the raw numerical result is returned without units attached.

Notes

• Subclasses must explicitly disable __IS_ABSTRACT__ to trigger full setup.

• Symbolic variables and parameter symbols are generated during class setup.

• Parameters provided at initialization can include units and are stored internally as magnitude/unit pairs.

• Numerical evaluation supports unit-aware input and output via __call__.

Methods

__init__(**kwargs)	Initialize a profile instance with specific parameter values.
from_dict(data)	Reconstruct a profile instance from a dictionary.
from_hdf5(h5obj[, name])	Reconstruct a profile from HDF5 attributes.
from_json(filepath)	Reconstruct a profile from a JSON file.
from_yaml(filepath)	Reconstruct a profile from a YAML file.
get_derived_profile(profile_name, **kwargs)	Access and instantiate a derived profile by name.
get_expression_latex([substitute])	Return the LaTeX representation of the profile's symbolic expression.
get_output_units(*argu)	Determine the output units of the operation given some set of input units.
get_parameters_latex()	Return a LaTeX table of the profile parameters.
lambdify_expression(expression)	Convert a symbolic expression into a callable function.
list_derived_profiles()	List all available derived profiles for this instance.
substitute_expression(expression)	Replace symbolic parameters with numerical values in an expression.
to_dict()	Serialize this profile to a minimal dictionary representation.
to_hdf5(h5obj[, name])	Store profile metadata into an HDF5 object as attributes.
to_json(filepath, **kwargs)	Serialize the profile to a JSON file.
to_yaml(filepath, **kwargs)	Serialize the profile to a YAML file.

Attributes

derived_profile_classes	Get the available derived profile classes for this instance.
parameter_symbols	Get the symbolic representations of the coordinate system parameters.
parameters	The parameters of this coordinate system.
variable_symbols	The symbols representing each of the coordinate axes in this coordinate system.
variables	The axes names present in this coordinate system.