BaseModel

class pisces.models.core.base.BaseModel(filepath: str | Path, *args, **kwargs)

Abstract base class for Pisces-compatible physical models.

The BaseModel defines the foundational logic and storage conventions for HDF5-backed physical models used throughout the Pisces framework. It provides a consistent interface for:

• Loading and validating model files

• Accessing physical fields, analytic profiles, and metadata

• Saving models from in-memory components

• Subclass extension via hooks and typed configuration

Model Structure

Pisces models are stored as structured HDF5 files with the following layout:

/
├── FIELDS/        # Physical field arrays (e.g., density, temperature)
├── PROFILES/      # Serialized analytic profile definitions
├── GRID/          # The spatial grid for the model.
└── attrs/         # Model metadata and identity tags

Each subclass is expected to match this layout and may define additional groups or attributes as needed. At minimum, each model must store its __model_class__ identifier at the root to verify identity during loading.

Access Patterns

This class supports dictionary-like access and assignment:

model["density"]  # returns field array
model["temperature"]  # returns profile object
model["description"]  # returns metadata string

"pressure" in model  # checks all three namespaces
model["mass"] = new_arr  # updates field

Subclassing Guidelines

To implement a new model type:

1. Subclass BaseModel and define the appropriate sampling or analysis methods.

2. Optionally override __post_init__() to customize setup after loading.

3. Optionally override _construct_model_file_skeleton() to define a custom layout.

4. Register the model in your configuration under [models.MyModelClass].

Methods

__init__(filepath, *args, **kwargs)	Load a Pisces model from an existing HDF5 file.
add_field(name[, element_shape, units, ...])	Add a new physical field to the model.
add_profile(name, profile[, overwrite])	Add a new analytic profile to the model.
copy_field(old_name, new_name)	Create a duplicate of an existing field under a new name.
copy_profile(old_name, new_name)	Create a duplicate of an existing profile under a new name.
from_components(filepath, grid, fields, ...)	Create and save a Pisces model from in-memory components.
get_active_hooks([names])	Return all active hook classes mixed into the model.
get_all_hooks([names])	Return all hook classes mixed into the model, regardless of activation status.
get_field(name)	Retrieve a physical field by name.
get_hook_class(hook_name)	Return the hook class associated with a given hook name.
get_hook_description(hook_cls)	Return the human-readable description for a given hook class.
get_hook_name(hook_cls)	Return the symbolic name for a given hook class.
get_profile(name)	Retrieve an analytic profile by name.
has_hook(hook)	Check if a given hook is mixed into the model (regardless of activation status).
list_fields()	List all physical fields currently stored in the model.
list_profiles()	List all analytic profiles currently stored in the model.
remove_field(name)	Remove a physical field from the model.
remove_profile(name)	Remove an analytic profile from the model.
rename_field(old_name, new_name)	Rename an existing field in the model.
rename_profile(old_name, new_name)	Rename an existing profile in the model.

Attributes

active_grid_axes	List of active axes in the model's grid.
config	Model-specific configuration settings.
coordinate_system	The coordinate system of the model's grid.
fields	Model field buffers.
grid	The spatial grid of the model.
handle	The open HDF5 file handle.
logger	Logger interface for this model.
metadata	Model metadata dictionary.
path	The path to the model's HDF5 file.
profiles	Model profile objects.