BaseHook#

class pisces.models.core.hooks.BaseHook[source]#

Base class for all Pisces model hooks.

This abstract base class defines a standardized interface and a set of conventions for modular “hooks” that can be mixed into Pisces model classes. Hooks encapsulate auxiliary logic such as sampling, initialization, diagnostics, or derived calculations, and are used to extend models non-intrusively without polluting the core behavior of the model.

Hint

An archetypal example of a hook is a particle sampler, which provides methods for generating or sampling particles from a model. This might not be possible in all models, but it is a common use-case and therefore can be mixed into models that support it.

Hooks inheriting from this base class gain access to a standardized structure for declaration, configuration, and integration.

Structure and Conventions#

Hooks follow a set of naming and structural conventions to ensure that they are clearly organized, easily discoverable, and do not interfere with model internals unless explicitly intended.

Feature Status Flag#

Each hook can be selectively enabled or disabled at the model level using a class-level flag with the format:

__<HookClassName>_HOOK_ENABLED__ = True  # or False

For example:

class MyClusterModel(BaseModel):
    __SphericalGalaxyClusterParticleHook_HOOK_ENABLED__ = False

This flag allows models to opt out of specific hook functionality without modifying the hook or base class definitions.

At the level of the hook class, the hook class will define the feature status flag and set it generically to True so that any class which mixes in the hook will have the hook enabled by default. This is done to ensure that hooks are enabled by default, but can be disabled on a per-model basis.

Metadata and Integration Support#

Hooks may optionally define metadata attributes:

  • _<HookClassName>_NAME: A short identifier string (e.g., "particle_sampler")

  • _<HookClassName>_DOC: A human-readable summary for documentation / summarizing.

These are useful for introspection or automated tooling but are not required.

Class Settings / Attributes#

Hooks can define class-level configuration settings using the pattern:

_<HookClassName>_<setting_name> = <value>

For example:

class ParticleSamplerHook(BaseHook):
    _ParticleSamplerHook_max_attempts = 1000


class MyCluster(
    SphericalGalaxyClusterModel,
    ParticleSamplerHook,
):
    _ParticleSamplerHook_max_attempts = (
        10  # Override the default
    )

This enables per-model customization of hook behavior.

Utility Methods#

Non-public helper methods in hooks should follow the naming pattern:

def _<HookClassName>_<method_name>(self, ...):
    ...

This avoids namespace pollution and clarifies which hook a utility belongs to.

Public API Methods#

Hooks may expose methods intended for use by the model or end user. These should:

  • Follow standard Python naming conventions (no leading underscore)

  • Avoid overly generic names like apply or run unless context-specific

  • Be explicitly documented

Invocation Lifecycle#

Hook methods may be:

  • Explicitly called by model methods

  • Automatically invoked by Pisces during construction or export

  • Used by other hooks

Hook logic should be self-contained and avoid side effects or global state.

Methods

__init__()

On this page

This Page