API reference¶

This page documents the public Python API. Hand-written guides:

Canonical schema — the canonical halo / forest / metadata contract.
Writing a reader plugin — reader plugins and their format-specific options.
Integration testing — running against ytree’s sample data.

Schema¶

The on-disk and in-memory contract every reader speaks.

astrosylva.HALO_DTYPE: numpy.dtype¶: The structured numpy dtype every reader yields and the writer consumes. See Canonical schema for the full field list and units.

class astrosylva.Forest(forest_id, halos, weight=1.0)[source]¶

Bases: object

A single self-contained merger-tree forest.

Parameters:

forest_id (int)
halos (ndarray)
weight (float)

forest_id: int¶

halos: ndarray¶

property n_halos: int¶

weight: float = 1.0¶

class astrosylva.Metadata(cosmology=<factory>, units=<factory>, halo_trees=<factory>, group_finder=<factory>, simulation=<factory>, format_version=2)[source]¶

Bases: object

Run metadata grouped to mirror the Galacticus HDF5 layout.

halo_trees holds the flags the original C tool wrote under /forestHalos as attributes (haloMassesIncludeSubhalos, forestsAreSelfContained, treesHaveSubhalos, velocitiesIncludeHubbleFlow). The user-facing YAML key is haloTrees; the HDF5 group is /forestHalos.

Parameters:

cosmology (dict[str, Any])
units (dict[str, Any])
halo_trees (dict[str, Any])
group_finder (dict[str, Any])
simulation (dict[str, Any])
format_version (int)

cosmology: dict[str, Any]¶

format_version: int = 2¶

group_finder: dict[str, Any]¶

groups()[source]¶

Return a mapping of HDF5 group path -> attributes dict.

Return type:: dict[str, dict[str, Any]]

halo_trees: dict[str, Any]¶

simulation: dict[str, Any]¶

units: dict[str, Any]¶

Reader framework¶

The abstract base class and the entry-point discovery helpers.

class astrosylva.readers.TreeReader(source, options=None)[source]¶

Bases: ABC

Abstract base for all tree-format readers.

Subclasses must:

set the class attribute name (and optionally aliases),
return reader-introspected metadata from metadata(),
yield Forest objects from __iter__,
report the forest count via __len__.

Parameters:

source (ReaderSource)
options (dict[str, Any] | None)

defaults()[source]¶

Reader-supplied default metadata.

Unlike metadata(), these values are not introspected from the input data — they’re per-format conventions that fill in a Galacticus output’s optional attributes when the user hasn’t spelled them out in their YAML. Config values silently override defaults; introspected values warn on conflict with config.

Subclasses override this to ship their format’s defaults; the base implementation returns an empty Metadata.

Return type:: Metadata

abstractmethod metadata()[source]¶

Return whatever metadata the reader can introspect from its input.

Return type:: Metadata

class astrosylva.readers.ReaderSource(paths)[source]¶

Bases: object

Free-form mapping of paths/handles that locate a reader’s input.

Each reader documents which keys it expects (e.g. Consistent-Trees needs input_path, forests_path, locations_path).

Parameters:: paths (dict[str, Any])

astrosylva.readers.discover_readers()[source]¶

Return a mapping of reader name (and aliases) to reader class.

Discovered via the astrosylva.readers entry point group.

Return type:: dict[str, type[TreeReader]]

astrosylva.readers.get_reader(name)[source]¶

Look up a reader class by name or alias.

Parameters:: name (str)
Return type:: type[TreeReader]

Bundled readers¶

class astrosylva.readers.consistent_trees.ConsistentTreesReader(source, options=None)[source]¶

Bases: TreeReader

Reader for the Consistent-Trees output of the Rockstar pipeline.

Parameters:

source (ReaderSource)
options (dict[str, Any] | None)

defaults()[source]¶

The four /forestHalos flags the legacy C tool always emitted.

These match the values in the original parameter.cfg shipped with rockstar2galacticus. They’re true for any standard Rockstar / Consistent-Trees run; users with different conventions can override per-key via metadata.haloTrees in their YAML.

Return type:: Metadata

metadata()[source]¶

Return whatever metadata the reader can introspect from its input.

Return type:: Metadata

class astrosylva.readers.lhalotree.LHaloTreeReader(source, options=None)[source]¶

Bases: TreeReader

Reader for the Millennium-style LHaloTree binary format.

Parameters:

source (ReaderSource)
options (dict[str, Any] | None)

metadata()[source]¶

Return whatever metadata the reader can introspect from its input.

Return type:: Metadata

class astrosylva.readers.sublink.SubLinkReader(source, options=None)[source]¶

Bases: TreeReader

Reader for SubLink HDF5 merger trees.

Parameters:

source (ReaderSource)
options (dict[str, Any] | None)

metadata()[source]¶

Return whatever metadata the reader can introspect from its input.

Return type:: Metadata

class astrosylva.readers.ahf.AHFReader(source, options=None)[source]¶

Bases: TreeReader

Reader for AHF halo catalogues + merger-tree files.

Parameters:

source (Any)
options (dict[str, Any] | None)

metadata()[source]¶

Return whatever metadata the reader can introspect from its input.

Return type:: Metadata

Writer¶

class astrosylva.writers.GalacticusWriter(path, metadata, *, chunk_size=4096)[source]¶

Bases: object

Write Galacticus-format HDF5, streaming forest-by-forest.

Parameters:

path (str | Path)
metadata (Metadata)
chunk_size (int)

Configuration¶

YAML config loading + the pydantic models that validate it.

astrosylva.config.load_config(path)[source]¶

Load and validate a YAML config file.

Parameters:: path (str | Path)
Return type:: Config

class astrosylva.config.Config(*, reader, writer, metadata=<factory>)[source]¶

Bases: BaseModel

Parameters:

reader (ReaderConfig)
writer (WriterConfig)
metadata (MetadataConfig)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class astrosylva.config.ReaderConfig(*, name, source=<factory>, options=<factory>)[source]¶

Bases: BaseModel

Parameters:

name (str)
source (dict[str, Any])
options (dict[str, Any])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class astrosylva.config.WriterConfig(*, output_path, options=<factory>)[source]¶

Bases: BaseModel

Parameters:

output_path (Path)
options (dict[str, Any])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class astrosylva.config.MetadataConfig(*, cosmology=<factory>, units=<factory>, haloTrees=<factory>, groupFinder=<factory>, simulation=<factory>)[source]¶

Bases: BaseModel

Parameters:

cosmology (dict[str, Any])
units (dict[str, Any])
haloTrees (dict[str, Any])
groupFinder (dict[str, Any])
simulation (dict[str, Any])

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Exceptions¶

exception astrosylva.AstroSylvaError[source]¶

Bases: Exception

Base class for all astrosylva errors.

exception astrosylva.ConfigError[source]¶

Bases: AstroSylvaError

Raised when the user-supplied configuration is invalid.

exception astrosylva.ReaderError[source]¶

Bases: AstroSylvaError

Raised when a reader cannot parse its input.

exception astrosylva.exceptions.WriterError[source]¶

Bases: AstroSylvaError

Raised when the writer cannot produce its output.

exception astrosylva.MetadataConflictWarning[source]¶

Bases: UserWarning

Reader-introspected metadata conflicts with config-supplied metadata.

The reader value wins; the warning surfaces both values so the user can decide whether the config is wrong.