yt

https://yt-project.org/docs/4.4.0/
Admin
yt is a community-developed analysis and visualization toolkit for volumetric data, with...
Tokens:2,363,819
Snippets:13,709
Trust Score:9.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example of switching compilers and installing mpi4py

Source: https://yt-project.org/docs/4.4.0/faq/index.html

This example demonstrates switching to GNU C compilers and then installing mpi4py using 'cc' as the MPICC. This is a common workaround on systems like Kraken.

```bash
$ module swap PrgEnv-pgi PrgEnv-gnu
$ env MPICC=cc python -m pip install mpi4py
```

--------------------------------

### Start the Jupyter notebook server

Source: https://yt-project.org/docs/4.4.0/quickstart/index.html

Navigate to the quickstart directory and launch the Jupyter lab environment.

```bash
cd yt/doc/source/quickstart
jupyter lab
```

--------------------------------

### Get Time Series with Setup Function

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/gadget/simulation_handling.html

Retrieves simulation outputs and applies a setup function to each dataset as it is loaded. The setup function can perform actions like printing the current time.

```python
# An example using the setup_function keyword
def print_time(ds):
    print(ds.current_time)
gs.get_time_series(setup_function=print_time)
```

--------------------------------

### Create an empty scene and add a VolumeSource and a Camera

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.scene.html

This example demonstrates the basic setup for volume rendering by creating an empty scene, adding a volume source based on density, and attaching a camera.

```python
import yt
from yt.visualization.volume_rendering.api import (
    Camera, Scene, create_volume_source)
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
sc = Scene()
source = create_volume_source(ds.all_data(), "density")
sc.add_source(source)
cam = sc.add_camera()
im = sc.render()
```

--------------------------------

### Launch Mapserver via Command Line

Source: https://yt-project.org/docs/4.4.0/visualizing/mapserver.html

Starts a micro-webserver on localhost to interactively explore a dataset. Requires the bottle package to be installed.

```bash
yt mapserver DD0050/DD0050
```

--------------------------------

### Configure Setup Function for Datasets

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.gadget.simulation_handling.html

Use a setup function to perform actions whenever a dataset is loaded during iteration.

```python
>>> # An example using the setup_function keyword
>>> def print_time(ds):
...     print(ds.current_time)
>>> gs.get_time_series(setup_function=print_time)
>>> for ds in gs:
...     SlicePlot(ds, "x", "Density").save()
```

--------------------------------

### GadgetSimulation Unit Setup

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/gadget/simulation_handling.html

Handles the setup of physical units for Gadget simulations, including cosmological and non-cosmological cases.

```APIDOC
## _set_units Method

### Description
Sets up the unit registry for the Gadget simulation, handling cosmological and non-cosmological specific unit conversions.

### Method
_set_units

### Parameters
None

### Request Body
None

### Response
None

### Response Example
None
```

--------------------------------

### Get yt Installation Information

Source: https://yt-project.org/docs/4.4.0/_modules/yt/utilities/command_line.html

Retrieves and prints information about the yt installation. Optionally updates the source if it's a git repository and can be updated. Can also write the version string to a specified output file.

```python
import os
import importlib.resources as importlib_resources


[docs]
class YTInstInfoCmd(YTCommand):
    name = ["instinfo", "version"]
    args = (
        {
            "short": "-u",
            "longname": "--update-source",
            "action": "store_true",
            "default": False,
            "help": "Update the yt installation, if able",
        },
        {
            "short": "-o",
            "longname": "--output-version",
            "action": "store",
            "default": None,
            "dest": "outputfile",
            "help": "File into which the current revision number will be stored",
        },
    )
    description = """
        Get some information about the yt installation

        """

    def __call__(self, opts):
        path = os.path.dirname(importlib_resources.files("yt"))
        vstring = _print_installation_information(path)
        if vstring is not None:
            print("This installation CAN be automatically updated.")
            if opts.update_source:
                update_git(path)
        elif opts.update_source:
            _print_failed_source_update()
        if vstring is not None and opts.outputfile is not None:
            open(opts.outputfile, "w").write(vstring)
```

--------------------------------

### Initialize Streamlines parameters

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.streamlines.html

Setup the dataset and define initial starting positions for streamline integration.

```python
>>> # Load the dataset and set some parameters
>>> ds = load("IsolatedGalaxy/galaxy0030/galaxy0030")
>>> c = np.array([0.5] * 3)
>>> N = 100
>>> scale = 1.0
>>> pos_dx = np.random.random((N, 3)) * scale - scale / 2.0
>>> pos = c + pos_dx
```

--------------------------------

### Install yt with All Optional Dependencies

Source: https://yt-project.org/docs/4.4.0/installing.html

Installs yt with all optional runtime dependencies included. This can be done for both stable releases and source builds.

```bash
$ python -m pip install --user yt[full]
$ python -m pip install --user -e .[full]
```

--------------------------------

### Install pyembree from source

Source: https://yt-project.org/docs/4.4.0/visualizing/unstructured_mesh_rendering.html

Clone the pyembree repository to install it from source. Ensure Embree is installed and its paths are correctly set if not in the default location.

```bash
git clone https://github.com/scopatz/pyembree
```

--------------------------------

### Install yt Stable Release with Pip

Source: https://yt-project.org/docs/4.4.0/installing.html

Installs the latest stable release of yt using pip. Ensure pip is up-to-date before installation.

```bash
$ python -m pip install --upgrade pip
$ python -m pip install --user yt
```

--------------------------------

### Configuration Setup

Source: https://yt-project.org/docs/4.4.0/_modules/yt/data_objects/static_output.html

Functions and callbacks for setting up yt configuration.

```APIDOC
## _setup_ds_store(ytcfg: YTConfig)

### Description
Sets up the ParameterFileStore for dataset configuration.

### Parameters
- **ytcfg** (YTConfig) - The yt configuration object.

### Global Variables
- **_ds_store** (ParameterFileStore | None) - The global ParameterFileStore instance.
```

```APIDOC
## _unsupported_object(ds, obj_name)

### Description
Returns a function that raises a YTObjectNotImplemented error.

### Parameters
- **ds** (Any) - The dataset object.
- **obj_name** (str) - The name of the unsupported object.
```

--------------------------------

### Install yt with Extra Requirements (Pip)

Source: https://yt-project.org/docs/4.4.0/installing.html

Installs yt along with specific extra requirements for data format parsing, such as 'ramses'. Combine multiple requirements with commas.

```bash
$ python -m pip install --upgrade pip
$ python -m pip install --user "yt[ramses]"
```

--------------------------------

### Get Global Start Index

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.athena.data_structures.html

Return the integer starting index for each dimension at the current level.

```APIDOC
## GET /api/get_global_startindex

### Description
Return the integer starting index for each dimension at the current level.

### Method
GET

### Endpoint
/api/get_global_startindex

### Response
#### Success Response (200)
- **start_indices** (list of integers) - The starting indices for each dimension.

#### Response Example
{
  "start_indices": [0, 0, 0]
}
```

--------------------------------

### Install Documentation Build Tools

Source: https://yt-project.org/docs/4.4.0/developing/building_the_docs.html

Installs the necessary tools for building yt documentation, including dependencies for executing code snippets and rendering notebooks. Run this from the top level of a local yt copy.

```bash
$ python -m pip install -e . -r requirements/docs.txt

```

--------------------------------

### Install pyembree with custom flags

Source: https://yt-project.org/docs/4.4.0/visualizing/unstructured_mesh_rendering.html

Install pyembree from source, specifying CFLAGS and LDFLAGS if Embree is installed in a non-standard path. This is necessary for the setup script to find the Embree libraries.

```bash
CFLAGS='-I/opt/local/include' LDFLAGS='-L/opt/local/lib' python setup.py install
```

--------------------------------

### Process Datasets After Setup Function

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/gadget/simulation_handling.html

Iterates through the datasets loaded with a setup function and performs operations like creating SlicePlots. This follows the example where a setup_function was provided.

```python
for ds in gs:
    SlicePlot(ds, "x", "Density").save()
```

--------------------------------

### Define Frontend Entry Points in setup.py

Source: https://yt-project.org/docs/4.4.0/developing/extensions.html

Use `entry_points` in `setup.py` to register custom frontend datasets for automatic loading by yt.

```python
setup(
    # ...,
    entry_points={
        "yt.frontends": [
            "myFrontend = my_frontend.api.MyFrontendDataset",
            "myOtherFrontend = my_frontend.api.MyOtherFrontendDataset",
        ]
    }
)


```

--------------------------------

### Configure Embree installation path

Source: https://yt-project.org/docs/4.4.0/visualizing/unstructured_mesh_rendering.html

Create an embree.cfg file in the yt-git directory to specify the Embree installation location. This method is used by the setup script if EMBREE_DIR is not set.

```text
/opt/local/
```

--------------------------------

### Initialize Camera with Defaults

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.camera.html

Create a camera using default settings for a given dataset.

```python
>>> import yt
>>> from yt.visualization.volume_rendering.api import Scene
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
>>> sc = Scene()
>>> cam = sc.add_camera(ds)
```

--------------------------------

### GET /get_next_nonzero_chunk

Source: https://yt-project.org/docs/4.4.0/_modules/yt/utilities/sdf.html

Finds the next chunk with non-zero data, starting from a given key.

```APIDOC
## GET /get_next_nonzero_chunk

### Description
Finds the next chunk with non-zero data, starting from a given key.

### Method
GET

### Endpoint
/get_next_nonzero_chunk

### Parameters
#### Query Parameters
- **key** (integer) - Required - The starting key index.
- **stop** (integer) - Optional - The maximum key index to search up to.

### Response
#### Success Response (200)
- **next_key** (integer) - The key of the next chunk with non-zero data.

#### Response Example
{
  "next_key": 55
}
```

--------------------------------

### Setup Field Methods

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.chombo.fields.html

Methods for initializing various field types and configurations.

```python
setup_extra_union_fields(_ptype ='all'_)
```

```python
setup_fluid_aliases(_ftype : str = 'gas'_) → None
```

```python
setup_fluid_fields()
```

```python
setup_fluid_index_fields()
```

```python
setup_particle_fields(_ptype_ , _ftype ='gas'_, _num_neighbors =64_)
```

```python
setup_smoothed_fields(_ptype_ , _num_neighbors =64_, _ftype ='gas'_)
```

--------------------------------

### Get Global Start Index for AMRGridPatch

Source: https://yt-project.org/docs/4.4.0/_modules/yt/data_objects/index_subobjects/grid_patch.html

Returns the integer starting index for each dimension at the current AMR level. It calculates this based on the parent grid's start index and the relative offset, or directly from domain edges if it's the top level.

```python
def get_global_startindex(self):
        """
        Return the integer starting index for each dimension at the current
        level.

        """
        if self.start_index is not None:
            return self.start_index
        if self.Parent is None:
            left = self.LeftEdge.d - self.ds.domain_left_edge.d
            start_index = left / self.dds.d
            return np.rint(start_index).astype("int64").ravel()

        pdx = self.Parent.dds.d
        di = np.rint((self.LeftEdge.d - self.Parent.LeftEdge.d) / pdx)
        start_index = self.Parent.get_global_startindex() + di
        self.start_index = (start_index * self.ds.refine_by).astype("int64").ravel()
        return self.start_index
```

--------------------------------

### Get Colorbrewer Colormap

Source: https://yt-project.org/docs/4.4.0/_modules/yt/funcs.html

Retrieves a colorbrewer colormap from the palettable library. Requires palettable to be installed.

```python
def get_brewer_cmap(cmap):
    """Returns a colorbrewer colormap from palettable"""
    try:
        import palettable
    except ImportError as exc:
        raise RuntimeError(
            "Please install palettable to use colorbrewer colormaps"
        ) from exc

    bmap = palettable.colorbrewer.get_map(*cmap)
    return bmap.get_mpl_colormap(N=cmap[2])
```

--------------------------------

### Create a scene using create_scene function

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.scene.html

This example shows an alternative method to initialize a scene using the `create_scene` function, which sets up defaults that can be modified later.

```python
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
```

```python
sc = yt.create_scene(ds)
# Modify camera, sources, etc...
im = sc.render()
```

--------------------------------

### Setup Post-Initialization Configuration

Source: https://yt-project.org/docs/4.4.0/_modules/yt.html

Executes post-initialization configuration callbacks for the yt library. This ensures that all settings and components are properly initialized after imports.

```python
# run configuration callbacks
_setup_postinit_configuration()
del _setup_postinit_configuration

```

--------------------------------

### Get thingking dependencies

Source: https://yt-project.org/docs/4.4.0/_modules/yt/utilities/sdf.html

Imports and returns necessary classes from the 'thingking' package. Raises ImportError if the package is not installed.

```python
import os
from collections import UserDict
from io import StringIO

import numpy as np

from yt.funcs import mylog




[docs]
def get_thingking_deps():
    try:
        from thingking.arbitrary_page import PageCacheURL
        from thingking.httpmmap import HTTPArray
    except ImportError:
        raise ImportError(
            "This functionality requires the thingking package to be installed"
        ) from None
    return HTTPArray, PageCacheURL

```

--------------------------------

### Import yt Configuration and Math Utilities

Source: https://yt-project.org/docs/4.4.0/_modules/yt.html

Imports configuration setup functions and mathematical utilities for parallel analysis and data manipulation.

```python
from yt.config import _setup_postinit_configuration
from yt.units.unit_systems import UnitSystem, unit_system_registry  # type: ignore

# Import some helpful math utilities
from yt.utilities.math_utils import ortho_find, periodic_position, quartiles
from yt.utilities.parallel_tools.parallel_analysis_interface import (
    communication_system,
    enable_parallelism,
    parallel_objects,
)

```

--------------------------------

### Setup Absolute Positions Field

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/open_pmd/fields.html

Combines coarse and offset particle positions to get absolute positions for each axis (x, y, z).

```python
def _abs_pos(axis):
    def ap(field, data):
        return np.add(
            data[ptype, f"particle_positionCoarse_{axis}"],
            data[ptype, f"particle_positionOffset_{axis}"],
        )

    return ap

for ax in "xyz":
    self.add_field(
        (ptype, f"particle_position_{ax}"),
        sampling_type="particle",
        function=_abs_pos(ax),
        units="m",
    )
```

--------------------------------

### Add a camera with default settings

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.scene.html

This example demonstrates how to add a camera to a scene using default settings, which are automatically determined based on the provided dataset.

```python
import yt
from yt.visualization.volume_rendering.api import Camera, Scene
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
sc = Scene()
sc.add_camera()
```

--------------------------------

### Get yt Version

Source: https://yt-project.org/docs/4.4.0/_modules/yt/funcs.html

Determines the current yt version by checking the Git commit hash of the yt installation directory. Requires 'gitpython'.

```python
def get_yt_version():
    import importlib.resources as importlib_resources

    version = get_git_version(os.path.dirname(importlib_resources.files("yt")))
    if version is None:
        return version
    else:
        v_str = version[:12].strip()
        if hasattr(v_str, "decode"):
            v_str = v_str.decode("utf-8")
        return v_str
```

--------------------------------

### Build documentation with Sphinx

Source: https://yt-project.org/docs/4.4.0/developing/building_the_docs.html

Navigate to the documentation directory and execute the build process.

```bash
cd $YT_GIT/doc
make html
```

--------------------------------

### Get SWIFT Header Info Attributes

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/swift/data_structures.html

Retrieves information from a specified header-style dataset within an HDF5 file. Requires 'h5py' to be installed.

```python
def _get_info_attributes(self, dataset):
    """
    Gets the information from a header-style dataset and returns it as a
    python dictionary.

    Example: self._get_info_attributes(header) returns a dictionary of all
    of the information in the Header.attrs.
    """

    with h5py.File(self.filename, mode="r") as handle:
        header = dict(handle[dataset].attrs)

    return header
```

--------------------------------

### Get ConfigLeaf Parent Tree

Source: https://yt-project.org/docs/4.4.0/_modules/yt/utilities/configuration_tree.html

Retrieves the hierarchical path of parent nodes leading to this ConfigLeaf. Returns a reversed list of nodes, starting from the root.

```python
def get_tree(self):
        node = self
        parents = []
        while node is not None:
            parents.append(node)
            node = node.parent

        return reversed(parents)
```

--------------------------------

### setup_handler(domain)

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.ramses.particle_handlers.html

Initializes a particle handler instance by setting the full file path.

```APIDOC
## setup_handler(domain)

### Description
Initialize an instance of the class. This automatically sets the full path to the file. This is not intended to be overridden in most cases.

### Parameters
#### Path Parameters
- **domain** (object) - Required - The domain object to initialize the handler with
```

--------------------------------

### Setup ART Particle Data Files

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/art/data_structures.html

Sets up the list of data files for an ARTParticleIndex. It assumes all data is in one file and constructs ARTParticleFile objects for each domain.

```python
def _setup_filenames(self):
        # no need for template, all data in one file
        template = self.dataset.filename_template
        ndoms = self.dataset.file_count
        cls = self.dataset._file_class
        self.data_files = []
        fi = 0
        for i in range(int(ndoms)):
            df = cls(self.dataset, self.io, template % {"num": i}, fi)
            fi += 1
            self.data_files.append(df)
```

--------------------------------

### Get Chombo Field Dictionary

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/chombo/io.html

Retrieves a dictionary mapping field names to their component numbers. This is populated from attributes starting with 'component_' in the HDF5 file.

```python
@property
def field_dict(self):
    if self._field_dict is not None:
        return self._field_dict
    field_dict = {}
    for key, val in self._handle.attrs.items():
        if key.startswith("component_"):
            comp_number = int(re.match(r"component_(\d+)", key).groups()[0])
            field_dict[val.decode("utf-8")] = comp_number
    self._field_dict = field_dict
    return self._field_dict
```

--------------------------------

### Initialize Simulation Parameters

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/gadget/data_structures.html

Sets up domain boundaries, periodicity, and file naming templates based on simulation parameters.

```python
        if self.domain_left_edge is None and self.parameters["BoxSize"] != 0:
            self.domain_left_edge = np.zeros(3, "float64")
            self.domain_right_edge = np.ones(3, "float64") * self.parameters["BoxSize"]

        self.domain_dimensions = np.ones(3, "int32")

        self.cosmological_simulation = 1
        self._periodicity = (True, True, True)

        prefix = os.path.abspath(
            os.path.join(
                os.path.dirname(self.parameter_filename),
                os.path.basename(self.parameter_filename).split(".", 1)[0],
            )
        )

        suffix = self.parameter_filename.rsplit(".", 1)[-1]
        if self.parameters["NumFiles"] > 1:
            self.filename_template = f"{prefix}.%(num)i.{suffix}"
        else:
            self.filename_template = self.parameter_filename

        self.file_count = self.parameters["NumFilesPerSnapshot"]
```

--------------------------------

### View Git Log with Options

Source: https://yt-project.org/docs/4.4.0/developing/developing.html

Displays a log of all revisions on the current branch. This example shows how to get a concise, decorated, and graphed log of all branches.

```bash
git log --oneline --decorate --graph --all
```

--------------------------------

### Setup magnetic field aliases for datasets

Source: https://yt-project.org/docs/4.4.0/_modules/yt/fields/magnetic_field.html

Examples of defining field info classes for Chombo and Gizmo datasets using magnetic field aliases.

```python
>>> from yt.fields.magnetic_field import setup_magnetic_field_aliases
>>> class PlutoFieldInfo(ChomboFieldInfo):
...     def setup_fluid_fields(self):
...         setup_magnetic_field_aliases(
...             self, "chombo", ["bx%s" % ax for ax in [1, 2, 3]]
...         )
>>> class GizmoFieldInfo(GadgetFieldInfo):
...     def setup_gas_particle_fields(self):
...         setup_magnetic_field_aliases(
...             self, "PartType0", "MagneticField", ftype="PartType0"
...         )
```

--------------------------------

### Setup Fluid Fields

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/flash/fields.html

Demonstrates how to set up fluid fields, including adding output fields and defining custom fields like specific total energy.

```APIDOC
## Setup Fluid Fields

### Description
This section describes the process of setting up fluid fields within the FLASH simulation, including adding predefined output fields and defining custom fields using Python functions.

### Methods
#### `setup_fluid_fields()`
This method initializes and configures the fluid fields for the simulation.

#### `add_output_field(field_name, sampling_type, units, display_name)`
Adds a predefined output field.

- **field_name** (tuple) - The name of the field, e.g., `("flash", "r001")`.
- **sampling_type** (string) - The type of sampling, e.g., "cell".
- **units** (string) - The units of the field.
- **display_name** (string) - The user-friendly display name.

#### `alias(new_field_name, existing_field_name, units)`
Creates an alias for an existing field.

- **new_field_name** (tuple) - The name for the new alias.
- **existing_field_name** (tuple) - The name of the field to alias.
- **units** (string) - The units for the alias.

#### `add_field(field_name, sampling_type, function, units)`
Defines a new custom field based on a function.

- **field_name** (tuple) - The name of the new field.
- **sampling_type** (string) - The type of sampling, e.g., "cell".
- **function** (function) - A Python function that computes the field values.
- **units** (string) - The units of the field.

### Example Usage
```python
# Assuming 'self' is an instance of FLASHFieldInfo and 'self.ds' is the dataset object

# Add energy group fields
for i in range(1, 1000):
    self.add_output_field(
        ("flash", f"r{i:03}"),
        sampling_type="cell",
        units="",
        display_name=f"Energy Group {i}",
    )

# Define and add specific total energy field if 'ener' is not present
def _ener(field, data):
    ener = data["flash", "eint"] + ekin(data)
    try:
        ener += data["flash", "magp"] / data["flash", "dens"]
    except Exception:
        pass
    return ener

self.add_field(
    ("gas", "specific_total_energy"),
    sampling_type="cell",
    function=_ener,
    units=unit_system["specific_energy"],
)
```
```

--------------------------------

### Import Style Guide Example

Source: https://yt-project.org/docs/4.4.0/developing/developing.html

Follow this import style for internal yt modules to avoid transitive imports and import symbols from their definition module.

```python
from yt.visualization.plot_window import ProjectionPlot
```

--------------------------------

### Manually Create and Render VolumeSource

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.render_source.html

This example shows how to manually create a VolumeSource, add it to a scene, set the camera, and render an image. It requires importing additional classes from `yt.visualization.volume_rendering.api`.

```python
import yt
from yt.visualization.volume_rendering.api import (
    Camera, Scene, create_volume_source)
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
sc = Scene()
source = create_volume_source(ds.all_data(), "density")
sc.add_source(source)
sc.add_camera()
im = sc.render()
```

--------------------------------

### Setup Handler Initialization - Python

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/ramses/field_handlers.html

Initializes a handler instance by setting up paths to the dataset files. It constructs the full path based on dataset structure and domain ID. Raises FileNotFoundError if the file does not exist.

```python
def setup_handler(self, domain):
        """
        Initialize an instance of the class. This automatically sets
        the full path to the file. This is not intended to be
        overridden in most cases.

        If you need more flexibility, rewrite this function to your
        need in the inherited class.
        """
        self.ds = ds = domain.ds
        self.domain = domain
        self.domain_id = domain.domain_id
        basename = os.path.abspath(ds.root_folder)
        iout = int(os.path.basename(ds.parameter_filename).split(".")[0].split("_")[1])

        if ds.num_groups > 0:
            igroup = ((domain.domain_id - 1) // ds.group_size) + 1
            full_path = os.path.join(
                basename,
                f"group_{igroup:05d}",
                self.fname.format(iout=iout, icpu=domain.domain_id),
            )
        else:
            full_path = os.path.join(
                basename, self.fname.format(iout=iout, icpu=domain.domain_id)
            )

        if os.path.exists(full_path):
            self.fname = full_path
        else:
            raise FileNotFoundError(
                f"Could not find {self._file_type} file (type: {self.ftype}). "
                f"Tried {full_path}"
            )

        if self.file_descriptor is not None:
            if ds.num_groups > 0:
                # The particle file descriptor is *only* in the first group
                self.file_descriptor = os.path.join(
                    basename, "group_00001", self.file_descriptor
                )
            else:
                self.file_descriptor = os.path.join(basename, self.file_descriptor)
```

--------------------------------

### Slice NumPy Array with Start, Stop, and Step

Source: https://yt-project.org/docs/4.4.0/reference/python_introduction.html

Demonstrates slicing a NumPy array to extract a subset of elements. Use this to get elements with a specific step.

```python
>>> print(my_array[50:60])
```

```python
>>> print(my_array[::2])
```

```python
>>> print(my_array[:-10])
```

--------------------------------

### Rebuild yt with Embree support

Source: https://yt-project.org/docs/4.4.0/visualizing/unstructured_mesh_rendering.html

Rebuild yt from source after installing Embree. Manually pass CFLAGS and LDFLAGS to the setup script if Embree is not in the default search path.

```bash
CFLAGS='-I/opt/local/include' LDFLAGS='-L/opt/local/lib' python setup.py develop
```

--------------------------------

### Import yt Configuration and Startup Tasks

Source: https://yt-project.org/docs/4.4.0/_modules/yt/utilities/command_line.html

Sets yt configuration for command-line use and imports argument parser and subparsers. This must be done before importing startup_tasks.

```python
import argparse
import base64
import json
import os
import pprint
import sys
import textwrap
from typing import Any

import numpy as np
from more_itertools import always_iterable

from yt.config import ytcfg
from yt.funcs import (
    download_file,
    enable_plugins,
    ensure_dir,
    ensure_dir_exists,
    get_git_version,
    mylog,
    update_git,
)
from yt.loaders import load
from yt.utilities.exceptions import YTFieldNotParseable, YTUnidentifiedDataType
from yt.utilities.metadata import get_metadata
from yt.visualization.plot_window import ProjectionPlot, SlicePlot

# isort: off
# This needs to be set before importing startup_tasks
ytcfg["yt", "internals", "command_line"] = True  # isort: skip
from yt.startup_tasks import parser, subparsers  # isort: skip # noqa: E402

# isort: on

# loading field plugins for backward compatibility, since this module
```

--------------------------------

### Get Chombo Particle Field Index

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/chombo/io.html

Retrieves a dictionary mapping particle field names to their component indices. This is populated from attributes starting with 'particle_' in the HDF5 file.

```python
@property
def particle_field_index(self):
    if self._particle_field_index is not None:
        return self._particle_field_index
    field_dict = {}
    for key, val in self._handle.attrs.items():
        if key.startswith("particle_"):
            comp_number = int(
                re.match(r"particle_component_(\d+)", key).groups()[0]
            )
            field_dict[val.decode("ascii")] = comp_number
    self._particle_field_index = field_dict
    return self._particle_field_index
```

--------------------------------

### Create and Render VolumeSource Automatically

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.render_source.html

This example demonstrates the easiest way to create a VolumeSource using `yt.volume_render` and then access the resulting source.

```python
import yt
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
im, sc = yt.volume_render(ds)
volume_source = sc.get_source(0)
```

--------------------------------

### Get Git Version

Source: https://yt-project.org/docs/4.4.0/_modules/yt/funcs.html

Retrieves the short 12-character Git commit hash for a given repository path. Returns None if 'gitpython' is not installed or if the path is not a valid Git repository.

```python
def get_git_version(path):
    try:
        import git
    except ImportError:
        print("Updating and precise version information requires ")
        print("gitpython to be installed.")
        print("Try: python -m pip install gitpython")
        return None
    try:
        repo = git.Repo(path)
        return repo.git.rev_parse("HEAD", short=12)
    except git.InvalidGitRepositoryError:
        # path is not a git repository
        return None
```

--------------------------------

### Initialize ART Simulation Parameters

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/art/data_structures.html

Sets up standard simulation parameters and cosmological constants required by yt from particle header values.

```python
                        v,
                        self.parameters[k],
                    )
            else:
                self.parameters[k] = v
        self.parameters_particles = particle_header_vals
        self.parameters.update(particle_header_vals)
        self.parameters["wspecies"] = wspecies[:n]
        self.parameters["lspecies"] = lspecies[:n]
        self.parameters["ng"] = self.parameters["Ngridc"]
        self.parameters["ncell0"] = self.parameters["ng"] ** 3
        self.parameters["boxh"] = self.parameters["boxsize"]
        self.parameters["total_particles"] = ls_nonzero
        self.domain_dimensions = np.ones(3, dtype="int64") * 2  # NOT ng

        # setup standard simulation params yt expects to see
        # Convert to float to please unyt
        self.current_redshift = float(self.parameters["aexpn"] ** -1.0 - 1.0)
        self.omega_lambda = float(particle_header_vals["Oml0"])
        self.omega_matter = float(particle_header_vals["Om0"])
        self.hubble_constant = float(particle_header_vals["hubble"])
        self.min_level = 0
        self.max_level = 0
        #        self.min_level = particle_header_vals['min_level']
        #        self.max_level = particle_header_vals['max_level']
        #        if self.limit_level is not None:
        #            self.max_level = min(
        #                self.limit_level, particle_header_vals['max_level'])
        #        if self.force_max_level is not None:
        #            self.force_max_level
        self.hubble_time = 1.0 / (self.hubble_constant * 100 / 3.08568025e19)
        self.parameters["t"] = a2b(self.parameters["aexpn"])
        self.current_time = self.quan(b2t(self.parameters["t"]), "Gyr")
        self.gamma = self.parameters["gamma"]
        mylog.info("Max level is %02i", self.max_level)
```

--------------------------------

### Initialize Simulation Dataset

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.gadget.simulation_handling.html

Load a simulation file using the yt library.

```python
>>> import yt
>>> gs = yt.load_simulation("my_simulation.par", "Gadget")
```

--------------------------------

### Get Git Command Help

Source: https://yt-project.org/docs/4.4.0/developing/developing.html

Use this command to access help documentation for any Git command. For example, to learn about the 'log' command, use 'git log --help'.

```bash
git <command> --help
```

--------------------------------

### Streamlines Class Initialization and Integration Example

Source: https://yt-project.org/docs/4.4.0/_modules/yt/visualization/streamlines.html

Demonstrates how to initialize the Streamlines class with a dataset and starting positions, then integrate the streamlines through the volume. This is useful for visualizing vector fields like velocity.

```python
import matplotlib.pyplot as plt
import numpy as np
from mpl_toolkits.mplot3d import Axes3D
import yt
from yt.visualization.api import Streamlines

# Load the dataset and set some parameters
ds = load("IsolatedGalaxy/galaxy0030/galaxy0030")
c = np.array([0.5] * 3)
N = 100
scale = 1.0
pos_dx = np.random.random((N, 3)) * scale - scale / 2.0
pos = c + pos_dx

# Define and construct streamlines
streamlines = Streamlines(
    ds, pos, "velocity_x", "velocity_y", "velocity_z", length=1.0
)
streamlines.integrate_through_volume()

# Make a 3D plot of the streamlines and save it to disk
fig = plt.figure()
ax = Axes3D(fig)
for stream in streamlines.streamlines:
    stream = stream[np.all(stream != 0.0, axis=1)]
    ax.plot3D(stream[:, 0], stream[:, 1], stream[:, 2], alpha=0.1)
plt.savefig("streamlines.png")
```

--------------------------------

### Access Simulation Datasets by Index or Slice

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/exodus_ii/simulation_handling.html

Allows accessing individual datasets by index or a range of datasets using slicing. If a float is provided as the start of a slice, it attempts to get a time range.

```python
def __getitem__(self, key):
        if isinstance(key, slice):
            if isinstance(key.start, float):
                return self.get_range(key.start, key.stop)
            # This will return a sliced up object!
            return DatasetSeries(self._pre_outputs[key], self.parallel)
        o = self._pre_outputs[key]
        fn, step = o
        o = load(fn, step=step)
        self._setup_function(o)
        return o

```

--------------------------------

### Setup Functions

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.ahf.fields.html

Functions for setting up various aspects of the YT project, including particle fields, fluid aliases, and smoothed fields.

```APIDOC
## Setup Functions

### Setup Extra Union Fields

#### Description
Sets up extra union fields. The `_ptype` parameter specifies the type of fields to set up.

#### Method
`setup_extra_union_fields(_ptype ='all'_)`

#### Parameters
- **_ptype** (str, optional) - The type of fields to set up. Defaults to 'all'.

#### Returns
None

### Setup Fluid Aliases

#### Description
Sets up aliases for fluid fields. The `_ftype` parameter specifies the fluid type.

#### Method
`setup_fluid_aliases(_ftype : str = 'gas'_)`

#### Parameters
- **_ftype** (str, optional) - The fluid type. Defaults to 'gas'.

#### Returns
None

### Setup Fluid Fields

#### Description
Sets up the standard fluid fields.

#### Method
`setup_fluid_fields()`

#### Returns
None

### Setup Fluid Index Fields

#### Description
Sets up the index fields for fluid data.

#### Method
`setup_fluid_index_fields()`

#### Returns
None

### Setup Particle Fields

#### Description
Sets up fields for particle data. Requires specifying the particle type and optionally the fluid type and number of neighbors.

#### Method
`setup_particle_fields(_ptype_ , _ftype ='gas'_, _num_neighbors =64_)`

#### Parameters
- **_ptype_** (any) - The particle type.
- **_ftype** (str, optional) - The fluid type. Defaults to 'gas'.
- **_num_neighbors** (int, optional) - The number of neighbors. Defaults to 64.

#### Returns
None

### Setup Smoothed Fields

#### Description
Sets up smoothed fields for particle data. Requires specifying the particle type and optionally the fluid type and number of neighbors.

#### Method
`setup_smoothed_fields(_ptype_ , _num_neighbors =64_, _ftype ='gas'_)`

#### Parameters
- **_ptype_** (any) - The particle type.
- **_num_neighbors** (int, optional) - The number of neighbors. Defaults to 64.
- **_ftype** (str, optional) - The fluid type. Defaults to 'gas'.

#### Returns
None
```

--------------------------------

### Create a volume rendering with LineSource

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.render_source.html

This example demonstrates initializing a dataset, creating a volume rendering, and adding random line segments to the scene.

```python
>>> import yt
>>> import numpy as np
>>> from yt.visualization.volume_rendering.api import LineSource
>>> from yt.units import kpc
>>> ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")
```

```python
>>> im, sc = yt.volume_render(ds)
```

```python
>>> nlines = 4
>>> vertices = np.random.random([nlines, 2, 3]) * 600 * kpc
>>> colors = np.random.random([nlines, 4])
>>> colors[:, 3] = 1.0
```

```python
>>> lines = LineSource(vertices, colors)
>>> sc.add_source(lines)
```

```python
>>> im = sc.render()
```

--------------------------------

### YTHaloParticleIndex Class

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/halo_catalog/data_structures.html

The YTHaloParticleIndex class provides functionality to index and retrieve halo particles from YTHaloCatalogDatasets. It includes methods for calculating particle index starts, detecting output fields, and getting halo values.

```APIDOC
## YTHaloParticleIndex Class

### Description
Provides particle index for getting halo particles from YTHaloCatalogDatasets.

### Methods

#### `__init__(self, ds, dataset_type)`
Initializes the YTHaloParticleIndex with a dataset and dataset type.

#### `_calculate_particle_index_starts(self)`
Creates a dictionary of halo ID offsets for each file.

#### `_detect_output_fields(self)`
Detects and sets the available fields, scalar fields, and units for the dataset.

#### `_get_halo_file_indices(self, ptype, identifiers)`
Gets the index of the data file list where a halo resides.

- **ptype** (str) - The particle type.
- **identifiers** (np.ndarray) - The halo identifiers.

#### `_get_halo_scalar_index(self, ptype, identifier)`
Gets the scalar index for a given halo identifier within its file.

- **ptype** (str) - The particle type.
- **identifier** (int) - The halo identifier.

#### `_get_halo_values(self, ptype, identifiers, fields, f=None)`
Retrieves field values for halo data containers.

- **ptype** (str) - The particle type.
- **identifiers** (np.ndarray) - The halo identifiers.
- **fields** (list) - A list of fields to retrieve.
- **f** (h5py.File, optional) - An already open h5py file object. Defaults to None.

#### `_identify_base_chunk(self, dobj)`
Placeholder method for identifying a base chunk.

#### `_read_halo_particle_field(self, fh, ptype, field, indices)`
Reads a specific particle field from a halo.

- **fh** (h5py.File) - The h5py file handle.
- **ptype** (str) - The particle type.
- **field** (str) - The name of the field to read.
- **indices** (np.ndarray) - The indices of the particles within the field.

#### `_read_particle_fields(self, fields, dobj, chunk=None)`
Reads specified particle fields from the dataset.

- **fields** (list) - A list of fields to read.
- **dobj** - The dataset object.
- **chunk** (optional) - Chunk information.

### Internal Attributes

- **`real_ds`**: A weak reference to the real dataset object.
- **`ds`**: The dataset object.
- **`dataset_type`**: The type of the dataset.
- **`data_files`**: A list of data files associated with the index.
- **`_halo_index_start`**: Dictionary mapping particle types to arrays of halo index starts.
- **`field_list`**: List of available fields.
- **`scalar_field_list`**: List of available scalar fields.
- **`io`**: The I/O handler for the dataset.
```

--------------------------------

### yt.startup_tasks Module

Source: https://yt-project.org/docs/4.4.0/reference/api/modules.html

Handles tasks that are executed during yt's startup.

```APIDOC
## yt.startup_tasks Module

### Description
Handles tasks that are executed during yt's startup.

### Classes
- **SetConfigOption** - Sets a configuration option.
- **SetExceptionHandling** - Sets exception handling.
- **YTParser** - A parser for yt configuration.

### Functions
- **turn_on_parallelism()** - Enables parallel processing.
```

--------------------------------

### Setup Deprecated Fields

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.fits.data_structures.html

Initializes or configures fields that are marked as deprecated.

```python
setup_deprecated_fields()
```

--------------------------------

### Setup Fluid Fields for Species Density

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/amrex/fields.html

Adds fluid fields for species fractions and their corresponding densities. It iterates through existing fields, identifies species fractions (starting with 'X('), and creates new fields for density.

```python
for _, field in self.ds.field_list:
            if field.startswith("X("):
                # We have a fraction
                sub = Substance(field)
                # Overwrite field to use nicer tex_label display_name
                self.add_output_field(
                    ("boxlib", field),
                    sampling_type="cell",
                    units="",
                    display_name=rf"X\left({sub.to_tex()}\right)",
                )
                self.alias(("gas", f"{sub}_fraction"), ("boxlib", field), units="")
                func = _create_density_func(("gas", f"{sub}_fraction"))
                self.add_field(
                    name=("gas", f"{sub}_density"),
                    sampling_type="cell",
                    function=func,
                    units=self.ds.unit_system["density"],
                    display_name=rf"\rho {sub.to_tex()}",
                )
```

--------------------------------

### Generate and Integrate 3D Streamlines

Source: https://yt-project.org/docs/4.4.0/visualizing/streamlines.html

This script demonstrates how to load a dataset, define random starting positions, create streamlines based on the gas velocity field, integrate them through the volume, and visualize the results. Ensure matplotlib and numpy are installed.

```python
import matplotlib.pyplot as plt
import numpy as np
from mpl_toolkits.mplot3d import Axes3D

import yt
from yt.units import Mpc
from yt.visualization.api import Streamlines

# Load the dataset
ds = yt.load("IsolatedGalaxy/galaxy0030/galaxy0030")

# Define c: the center of the box, N: the number of streamlines, 
# scale: the spatial scale of the streamlines relative to the boxsize, 
# and then pos: the random positions of the streamlines.
c = ds.domain_center
N = 100
scale = ds.domain_width[0]
pos_dx = np.random.random((N, 3)) * scale - scale / 2.0
pos = c + pos_dx

# Create streamlines of the 3D vector velocity and integrate them through
# the box defined above
streamlines = Streamlines(
    ds,
    pos,
    ("gas", "velocity_x"),
    ("gas", "velocity_y"),
    ("gas", "velocity_z"),
    length=1.0 * Mpc,
    get_magnitude=True,
)
streamlines.integrate_through_volume()

# Create a 3D plot, trace the streamlines through the 3D volume of the plot
fig = plt.figure()
ax = Axes3D(fig, auto_add_to_figure=False)
fig.add_axes(ax)
for stream in streamlines.streamlines:
    stream = stream[np.all(stream != 0.0, axis=1)]
    ax.plot3D(stream[:, 0], stream[:, 1], stream[:, 2], alpha=0.1)

# Save the plot to disk.
plt.savefig("streamlines.png")

```

--------------------------------

### Setup Functions

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.frontends.owls_subfind.fields.html

Functions for setting up various fields and aliases.

```APIDOC
## Setup Functions

### Description
Functions used to configure and set up different aspects of the simulation data, including particle fields, fluid aliases, and smoothed fields.

### `setup_extra_union_fields(_ptype ='all'_)`

#### Description
Sets up extra union fields. The `_ptype` parameter specifies the particle type.

#### Parameters
- **_ptype** (string): The particle type. Defaults to 'all'.

#### Returns
None

### `setup_fluid_aliases(_ftype : str = 'gas'_)`

#### Description
Sets up aliases for fluid fields, simplifying access to common fluid properties.

#### Parameters
- **_ftype** (string): The fluid type for which to set up aliases. Defaults to 'gas'.

#### Returns
None

### `setup_fluid_fields()`

#### Description
Sets up the standard fluid fields.

#### Returns
None

### `setup_fluid_index_fields()`

#### Description
Sets up index fields for fluid data.

#### Returns
None

### `setup_particle_fields(_ptype_ , _ftype ='gas'_, _num_neighbors =64_)`

#### Description
Sets up particle fields for a given particle type and fluid type.

#### Parameters
- **_ptype_**: The particle type.
- **_ftype** (string): The fluid type. Defaults to 'gas'.
- **_num_neighbors** (integer): The number of neighbors to consider. Defaults to 64.

#### Returns
None

### `setup_smoothed_fields(_ptype_ , _num_neighbors =64_, _ftype ='gas'_)`

#### Description
Sets up smoothed particle fields, often used for calculating properties like density and pressure.

#### Parameters
- **_ptype_**: The particle type.
- **_num_neighbors** (integer): The number of neighbors to consider. Defaults to 64.
- **_ftype** (string): The fluid type. Defaults to 'gas'.

#### Returns
None
```

--------------------------------

### Get Athena Read Table Offset

Source: https://yt-project.org/docs/4.4.0/_modules/yt/frontends/athena/io.html

Reads a file line by line to find the 'CELL_DATA' or 'POINT_DATA' marker and returns the file offset immediately following it. This is crucial for locating the start of the data table in Athena output files.

```python
def get_read_table_offset(f):
    line = f.readline()
    while True:
        splitup = line.strip().split()
        chkc = chk23("CELL_DATA")
        chkp = chk23("POINT_DATA")
        if chkc in splitup or chkp in splitup:
            f.readline()
            read_table_offset = f.tell()
            break
        line = f.readline()
    return read_table_offset
```

--------------------------------

### Load Dataset and Initialize Camera Parameters

Source: https://yt-project.org/docs/4.4.0/reference/api/yt.visualization.volume_rendering.old_camera.html

Loads a dataset and sets up initial parameters for the camera, including center, viewpoint vector, width, and resolution. Ensure the dataset is accessible.

```python
ds = load("DD1701")  # Load a dataset
c = [0.5] * 3  # Center
L = [1.0, 1.0, 1.0]  # Viewpoint
W = np.sqrt(3)  # Width
N = 1024  # Pixels (1024^2)
```
Tokens:
Raw