pisces.models.core.hooks.ParticleGenerationHook.generate_particles#

abstract ParticleGenerationHook.generate_particles(filename: str | Path, num_particles: dict[str, int], **kwargs) → ParticleDataset[source]#

Convert this model into a particle-based representation.

This method creates a synthetic particle dataset that captures the physical structure described by the model. The returned dataset contains positions, velocities, masses, and other relevant fields for each particle, and is suitable for use in mock observations, simulations, or analysis pipelines.

The specific method of generation—such as random sampling, grid population, or numerical evaluation—depends on the model and the hook subclass providing the implementation.

Common use cases include:

  • Creating Monte Carlo realizations of galaxy clusters

  • Exporting a model as particles for visualization or N-body input

  • Generating mock data for pipelines expecting discrete samples

Parameters:

  • filename (str or Path) – The path to save the generated particle dataset. This can be a string representing a file path or a Path object. The dataset will be saved in a format compatible with Pisces particle datasets (e.g., HDF5, FITS).

  • num_particles (dict of str, int) –

    A dictionary specifying the number of particles to generate for each component or type in the model. The keys are component names (e.g., “gas”, “dark_matter”, “stars”) and the values are the number of particles to generate for that component.

    Depending on the model and the hook implementation, this may only permit certain particle types / names and possible limits on the number of particles permitted.

  • **kwargs – Optional keyword arguments that control sampling resolution, included components, or output structure. Supported options vary by model.

Returns:

A particle dataset containing the generated realization of this model. Includes physical fields (e.g., positions, velocities, mass) and metadata specific to the model type.

Return type:

ParticleDataset