Analysis

opencosmo.analysis.reduce(dataset, function, operation='sum', all=False, plotting_function=None, evaluate_kwargs=None, plotting_kwargs=None, **ekwargs)

Combine results from several MPI processes into a single result. By defualt, the result is returned to the root process (rank 0), while all other processes are returned None. You can return the result to all processes by setting all = True.

Under the hood, this function uses evaluate to perform the computation. Besides the specific arguments mentioned below, you should pass in the arguments that you would if you were calling evaluate directly (including vectorize, which you will probably want to set to True)

If you like, you can also pass a plotting function

For example, to compute a halo mass function across a large simulation:

import matplotlib.pyplot as plt
import numpy as np
import opencosmo as oc
from opencosmo.analysis import reduce

ds = oc.open("haloproperties.hdf5")
def halo_mass_function(fof_halo_mass, log_bins, box_size):
    log_mass = np.log10(fof_halo_mass)
    hist, _ = np.histogram(log_mass, log_bins)
    return hist / np.diff(log_bins) / box_size**3


def make_plot(halo_mass_function, log_bins, path, **kwargs):
    bin_centers = 0.5 * (log_bins[:-1] + log_bins[1:])
    plt.plot(bin_centers, halo_mass_function)
    plt.semilogy()
    plt.savefig(path)


bins = np.linspace(10, 15)
box_size = ds.header.simulation["box_size"].value
plotting_arguments = {"path": "hmf.png"}
evalute_kwargs = {"vectorize": True, "format": "numpy", "box_size": box_size, "log_bins": bins}

reduce(
    ds,
    halo_mass_function,
    plotting_function=make_plot,
    evalute_kwargs=evalute_kwargs,
    plotting_kwargs=plotting_arguments,
)

When using this function, it’s generally recommended you add a **kwargs to your plotting function since it will recieve all of the evaulate keyword arugments in addition to the plotting arguments.

This function checks that the values returned from the different processes can actually be combined, and throws an error if not. The most common failure cases is when the arrays returned by various processes are not the same size.

Althoug the example above only returns a single array, you may return multiple arrays as a dictionary. Each array in the dictionary will be processed seperately.

Parameters:

  • dataset (Dataset | Collection) – Any OpenCosmo dataset or collection which supports evaluate

  • function (Callable) – A function to compute on the dataset. See the documentation for evaluate for your given data type for details on the expected signature.

  • operation (string, "sum" | "prod" | "avg", default = "sum") – The operation to use when performing the reduction. If “avg”, the averages will be weighted by the relative sizes of the datasets on each rank.

  • all (bool, default = False) – Whether to return the result to all processes or just the root process. If False, all processes besides the root process will recieve None

  • plotting_function (Optional[Callable], default = None) – A function that performs some plotting or post-processing. Since the result from evaluate function is always a dictionary, this function should take arguments with the same name as the keys of this dictionary. The evaluate_kwargs will also be passed into this function as keyword arguments.

  • plotting_kwargs (dict[str, Any]) – Additional keyword arguments to pass into the plotting function.

  • **evaluate_kwargs (Any) – Additional keyword arguments that will be passed directly into dataset.evalute and plotting_function (if applicable)

Returns:

results – The result of the reduction. If all = False (the default) only the root process will recieve the results with the remaining processes receiving None. If all = True, all processes will recieve the results

Return type:

dict[str, np.ndarray] | None

opencosmo.analysis.create_yt_dataset(data, compute_xray_fields=False, return_source_model=False, source_model_kwargs={})

Converts particle data to a yt dataset. Note that yt is generally developed with AMR codes in mind, but support for SPH codes is continually being added. yt’s documentation can be found here.

If compute_xray_fields is enabled, X-ray emissivity and luminosity fields will be added using pyxsim, which generates photon samples from gas properties.

Parameters:

  • data (dict of astropy.table.Table) – A dictionary of particle datasets. Must include at least positions and masses.

  • compute_xray_fields (bool, optional) – Whether or not to compute X-ray luminosities with pyxsim. Uses CIESourceModel, which considers thermal emission from gas assuming collisional ionization equilibrium.

  • return_source_model (bool, optional) – Whether or not to return the pyxsim source model for further interaction, such as computing additional luminosities in different frequency bands or generating synthetic observations.

  • source_model_kwargs (dict, optional) – Keyword arguments passed to the CIESourceModel constructor in pyxsim. These can include parameters like emin, emax, nbins, abund_table, etc., to control the spectral resolution and emission model behavior. If None, default values will be used for all source model parameters.

Returns:

  • ds (yt.data_objects.static_output.Dataset) – A yt dataset built from the input particle data, with additional fields (e.g., X-ray luminosities) if requested.

  • source_model (pyxsim.source_models.CIESourceModel, optional) – Returned only if return_source_model=True.

Return type:

Union[YT_Dataset, Tuple[YT_Dataset, CIESourceModel]]

opencosmo.analysis.visualize_halo(halo_id, data, yt_ds=None, projection_axis='z', north_vector=None, length_scale='top left', text_color='lightgray', width=None, manual_axis_alignment=False)

Creates a figure showing particle projections of dark matter, stars, gas, and/or gas temperature for given halo. If any of the listed particle types are not present in the dataset, this will create a horizontal arrangement with only the particles/fields that are present. Otherwise, creates a 2x2-panel figure. Each panel is an 800x800 pixel array.

To customize the arrangement of panels, fields, colormaps, etc., see halo_projection_array().

Parameters:

  • halo_id (int) – Identifier of the halo to be visualized.

  • data (opencosmo.StructureCollection) – OpenCosmo StructureCollection object containing both halo properties and particle data (e.g. output of opencosmo.open([haloproperties, sodbighaloparticles])).

  • projection_axis (str, optional) – Data is projected along this axis ("x", "y", or "z"). Overridden if params["projection_axes"] is provided

  • length_scale (str or None, optional) –

    Optionally add a horizontal bar denoting length scale in Mpc.

    Options:

    • "top left": add to top left panel

    • "top right": add to top right panel

    • "bottom left": add to bottom left panel

    • "bottom right": add to bottom right panel

    • "all top": add to all panels on top row

    • "all bottom": add to all panels on bottom row

    • "all left": add to all panels on leftmost column

    • "all right": add to all panels on rightmost column

    • "all": add to all panels

    • None: no length scale on any panel

  • text_color (str, optional) – Set the color of all text annotations. Default is “gray”

  • width (float, optional) – Width of each projection panel in units of R200 for the halo. If None, plots full subvolume around halo.

  • yt_ds (Optional[YT_Dataset])

  • north_vector (Optional[list[float]])

  • manual_axis_alignment (Optional[bool])

Returns:

A matplotlib Figure object.

Return type:

matplotlib.figure.Figure

opencosmo.analysis.halo_projection_array(halo_ids, data, yt_ds=None, field=('dm', 'particle_mass'), weight_field=None, projection_axis='z', north_vector=None, cmap='gray', cmap_norm=None, zlim=None, params=None, length_scale=None, text_color='lightgray', width=None, manual_axis_alignment=False)

Creates a multipanel figure of projections for different fields and/or halos.

By default, creates an arrangement of dark matter particle projections with the same shape as halo_ids. Each panel is an 800x800 pixel array.

Customizable — can change which fields are plotted for which halos, their order, weighting, etc., using params.

NOTE: Dark matter particle masses often aren’t stored for gravity-only simulations because the particles all have the same mass by construction. The particles are also labelled as “gravity” particles in this case instead of “dm” particles in the data. To project dark matter particles in gravity only, one can use the ("gravity", "particle_ones") field in place of ("dm", "particle_mass"). This will produce the same final image.

Parameters:

  • halo_ids (int or 2D array of int) – Unique ID of the halo(s) to be visualized. The shape of halo_ids sets the layout of the figure (e.g., if halo_ids is a 2x3 array, the outputted figure will be a 2x3 array of projections). To leave a panel in the outputted figure blank, set the corresponding entry into the halo_ids array to None. If int, a single panel is output while preserving formatting.

  • data (opencosmo.StructureCollection) – OpenCosmo StructureCollection dataset containing both halo properties and particle data (e.g., output of opencosmo.open([haloproperties, sodbighaloparticles])).

  • yt_ds (yt dataset or 2D array of yt datasets, optional) – Pre-loaded yt dataset (e.g., output of opencosmo.analysis.create_yt_dataset()). If None, halo_projection_array will internally search for the halo ID to create the yt dataset.

  • field (tuple of str, optional) – Field to plot for all panels. Follows yt naming conventions (e.g., ("dm", "particle_mass"), ("gas", "temperature")). Overridden if params["fields"] is provided.

  • weight_field (tuple of str, optional) – Field to weight by during projection. Follows yt naming conventions. Overridden if params["weight_fields"] is provided.

  • projection_axis (str, int, or 3-element sequence of floats, optional) – Data is projected along this axis ("x", "y", or "z"), or, alternatively, (0, 1, or 2). projection_axis is forwarded to the normal parameter of ParticleProjectionPlot. An arbitrary projection axis may be provided as a 3-element sequence of floats. Overridden if params["projection_axes"] is provided

  • north_vector (str, int, or 3-element sequence of floats, optional) – Sets the north vector of the projection (i.e. which axis corresponds to “up” in the final image). Setting north_vector requires setting a projection_axis that is perpendicular to north_vector. If north_vector is not set, yt will choose a north vector internally. north_vector is forwarded to the north_vector parameter of ParticleProjectionPlot.

  • cmap (str) – Matplotlib colormap to use for all panels. Overridden if params["cmaps"] is provided. See https://matplotlib.org/stable/gallery/color/colormap_reference.html for named colormaps.

  • cmap_norm (Normalize) – Normalization for matplotlib colormap (e.g. for setting norm=matplotlib.colors.SymLogNorm()). If None, defaults to matplotlib.colors.LogNorm(vmin=zlim[0], vmax=zlim[1])

  • zlim (tuple of float, optional) – Colorbar limits for field. Overridden if params["zlims"] is provided.

  • length_scale (str or None, optional) – Optionally add a horizontal bar denoting length scale in Mpc.

  • manual_axis_alignment (bool, optional) –

    Generate images by directly calling yt.OffAxisParticleProjectionPlot, which can give more flexibility for managing image orientation. If False, halo_projection_array will use yt.ParticleProjectionPlot.

    Options:

    • "top left": add to top left panel

    • "top right": add to top right panel

    • "bottom left": add to bottom left panel

    • "bottom right": add to bottom right panel

    • "all top": add to all panels on top row

    • "all bottom": add to all panels on bottom row

    • "all left": add to all panels on leftmost column

    • "all right": add to all panels on rightmost column

    • "all": add to all panels

    • None: no length scale shown

  • params (dict, optional) –

    Dictionary of customization parameters for the projection panels. Overrides defaults. All values must be 2D arrays with the same shape as halo_ids.

    Keys may include:

    • "fields": 2D array of fields to plot (yt naming conventions)

    • "weight_fields": 2D array of projection weights (or None)

    • "projection_axes": 2D array of projection axes (“x”, “y”, or “z”)

    • "zlims": 2D array of colorbar limits (log-scaled)

    • "labels": 2D array of panel labels (or None)

    • "cmaps": 2D array of Matplotlib colormaps for each panel

    • "cmap_norms": 2D array of colormap normalization method (e.g. matplotlib.colors.LogNorm())

    • "widths": 2D array of widths in units of R200

  • text_color (str, optional) – Set the color of all text annotations. Default is “gray”

  • width (float, optional) – Width of each projection panel in units of R200 for the halo. Overridden if params["widths"] is provided. If None, plots full subvolume.

Returns:

A Matplotlib Figure object.

Return type:

matplotlib.figure.Figure

opencosmo.analysis.animate_halos(halo_ids, data, func='visualize_halo', rotations='y', frames=30, dpi=100, normal0='z', north0='y', **kwargs)

Creates an animation of one or more halo projections while rotating the viewing direction.

The animation is constructed by repeatedly calling either visualize_halo or halo_projection_array for a sequence of projection orientations and stacking the individual frames into an animation. The viewing orientation evolves according to rotations, beginning from the initial projection axis normal0 and initial “up” direction north0.

By default, this function animates a single halo using visualize_halo while rotating about the y-axis. It can also animate a customizable multipanel projection layout by setting func="halo_projection_array" and passing a 2D arrangement of halo IDs.

Example usage for visualizing the most massive halo in a dataset:

import opencosmo as oc
from opencosmo.analysis import animate_halos

# fetch data and ID for most massive halo
ds = oc.open("haloproperties.hdf5", "haloparticles.hdf5").sort_by("sod_halo_mass").take(1, at="end")
halo_id = ds["halo_properties"].select("unique_tag").get_data()

# create a 30-frame animation that rotates the object once about the y-axis, then once about the x-axis.
anim = animate_halos(halo_id, ds, rotations=["y", "x"], frames=30)
anim.save("animation.gif", fps=10)
Parameters:

  • halo_ids (int or array of int) –

    Unique ID of the halo(s) to be animated. halo_ids is forwarded to the parameter of the same name in either visualize_halo or halo_projection_array, depending on the value of func.

    When func="visualize_halo", only a single halo ID is allowed. When func="halo_projection_array", halo_ids can be an int, list, or 2D array.

  • data (opencosmo.StructureCollection) – OpenCosmo StructureCollection containing the halo properties and particle data needed to create yt datasets for the requested halos. For example, this may be the output of opencosmo.open(["haloproperties.hdf5", "haloparticles.hdf5"]).

  • func (str, optional) –

    Name of the plotting function used to generate each animation frame.

    • "visualize_halo": animate a single halo using visualize_halo.

    • "halo_projection_array": animate a panel array using halo_projection_array.

  • rotations (str or sequence of str, optional) –

    Specification for how the camera rotates during the animation.

    For example, rotations = "x" rotates the object once about the x-axis, while rotations = ["x", "y"] rotates the object once about the x-axis, then once about the y-axis. Partial rotations can be defined by prepending the string with a float (e.g. rotations=["0.5*x", "0.25*y"] does half a rotation about the x-axis, then a quarter rotation about the y-axis). Prepending the string with a negative value reverses the rotation direction.

  • frames (int, optional) – Total number of frames in the animation.

  • dpi (int, optional) – Resolution of the persistent display figure used to assemble the animation. This also controls the effective pixel size of the output animation.

  • normal0 (str, int, or 3-tuple of float, optional) – Projection axis for the initial frame.

  • north0 (str, int, or 3-tuple of float, optional) – Initial north vector, i.e. the initial “up” direction in the image plane. north0 muat be perpendicular to normal0.

  • **kwargs –

    Additional keyword arguments passed directly to the selected plotting function (either visualize_halo or halo_projection_array). This can be used to customize the field being projected, color normalization, labels, plot width, colormap, and so on.

    Note that projection_axis, north_vector, yt_ds, and manual_axis_alignment are set internally by animate_halo and will be overridden regardless of values passed through kwargs.

Returns:

Matplotlib animation object.

Return type:

matplotlib.animation.FuncAnimation

opencosmo.analysis.ParticleProjectionPlot(*args, **kwargs)

Wrapper for yt.ParticleProjectionPlot.

Creates a 2D projection plot of particle-based data along a specified axis.

Parameters:

  • *args – Positional arguments passed directly to yt.ParticleProjectionPlot.

  • **kwargs – Keyword arguments passed directly to yt.ParticleProjectionPlot.

Returns:

A ParticleProjectionPlot object containing the particle projection plot.

Return type:

yt.visualization.plot_window.ParticleProjectionPlot

opencosmo.analysis.ProjectionPlot(*args, **kwargs)

Wrapper for yt.ProjectionPlot.

Creates a 2D projection plot of particle-based data along a specified axis. Smoothing is applied to SPH particle data over the smoothing length

Parameters:

  • *args – Positional arguments passed directly to yt.ProjectionPlot.

  • **kwargs – Keyword arguments passed directly to yt.ProjectionPlot.

Returns:

A ProjectionPlot object containing the smoothed particle projection plot.

Return type:

yt.visualization.plot_window.ProjectionPlot

opencosmo.analysis.SlicePlot(*args, **kwargs)

Wrapper for yt.SlicePlot.

Creates a 2D slice plot of particle-based data along a specified axis. Smoothing is applied to SPH particle data over the smoothing length

Parameters:

  • *args – Positional arguments passed directly to yt.SlicePlot.

  • **kwargs – Keyword arguments passed directly to yt.SlicePlot.

Returns:

A PlotWindow object containing the particle slice plot.

Return type:

yt.visualization.plot_window.PlotWindow

opencosmo.analysis.ProfilePlot(*args, **kwargs)

Wrapper for yt.ProfilePlot.

Creates a bin-averaged profile of a dependent variable as a function of one or more independent variables.

Parameters:

  • *args – Positional arguments passed directly to yt.ProfilePlot.

  • **kwargs – Keyword arguments passed directly to yt.ProfilePlot.

Returns:

A PlotWindow object containing the profile plot.

Return type:

yt.visualization.plot_window.PlotWindow

opencosmo.analysis.PhasePlot(*args, **kwargs)

Wrapper for yt.PhasePlot.

Creates a 2D histogram (phase plot) showing how one quantity varies as a function of two others, useful for visualizing thermodynamic or structural relationships (e.g., temperature vs. density colored by mass).

Parameters:

  • *args – Positional arguments passed directly to yt.PhasePlot.

  • **kwargs – Keyword arguments passed directly to yt.PhasePlot.

Returns:

A PlotWindow object containing the phase plot.

Return type:

yt.visualization.plot_window.PlotWindow