FDSReader

https://firedynamics.github.io/fdsreader
Admin
FDSReader is a Python library for reading, processing, and exporting output and data files generated...
Tokens:66,594
Snippets:324
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get patch orientations

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Returns a list of all available patch orientations.

```python
@property
def orientations(self):
    """Return all orientations for which there is data available.
    """
    return [p.orientation for p in self._patches]
```

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

### Get Pickle Filename

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Constructs the file path for a pickled simulation object based on the root directory and simulation ID.

```python
@classmethod
def _get_pickle_filename(cls, root_path: str, chid: str) -> AnyStr:
    """Get the filename used to save the pickled simulation.
    """
    return os.path.join(root_path, chid + ".pickle")
```

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

### Create PyVista mesh from isosurface data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/isof/isosurface.html

Converts vertices and triangles into a PyVista PolyData object. Requires the pyvista package to be installed.

```python
    def get_pyvista_mesh(self, vertices: np.ndarray, triangles: np.ndarray):
        """Creates a PyVista mesh from the data.
        """
        try:
            from pyvista import PolyData

            triangles = np.hstack(np.append(np.full((triangles.shape[0], 1), 3), triangles, axis=1))
            return PolyData(vertices, triangles)
        except ImportError:
            raise ImportError("The 'get_pyvista_mesh' method requires the PyVista python-package to"
                              " be installed. Consider installing it via 'pip install pyvista'.")
```

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

### Surface.__init__

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/fds_classes/surface.html

Initializes a new Surface object with specified material and visual properties.

```APIDOC
## Surface(name, tmpm, material_emissivity, surface_type, texture_width, texture_height, texture_map, rgb, transparency)

### Description
Creates a new Surface instance to describe bounding surface properties for FDS obstructions and vents.

### Parameters
- **name** (str) - Required - Name of the surface.
- **tmpm** (float) - Required - Material temperature property.
- **material_emissivity** (float) - Required - Emissivity of the material.
- **surface_type** (int) - Required - Type of the surface.
- **texture_width** (float) - Required - Width of the texture.
- **texture_height** (float) - Required - Height of the texture.
- **texture_map** (Optional[str]) - Required - Path to the texture map.
- **rgb** (Tuple[float, float, float]) - Required - Color of the surface as a 3-element tuple.
- **transparency** (float) - Required - Transparency value (alpha channel).
```

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

### get_nearest_patch(x, y, z)

Source: https://firedynamics.github.io/fdsreader/bndf.html

Gets the patch with the least distance to a point.

```APIDOC
## get_nearest_patch(x, y, z)

### Description
Gets the patch of the SubObstruction that has the least distance to the given point. If there are multiple patches with the same distance, a random one will be selected.
```

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

### Perform file and directory utilities

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/utils/data.html

Functions for generating MD5 hashes and locating SMV simulation files.

```python
def create_hash(path: str):
    """Returns the md5 hash as string for the given file.
    """
    return str(hashlib.md5(open(path, 'rb').read()).hexdigest())
```

```python
def scan_directory_smv(directory: str):
    """Scanning a directory non-recursively for smv-files.

    :param directory: The directory that will be scanned for smv files.
    :returns: A list containing the path to each smv-file found in the directory.
    """
    return glob.glob(directory + "/**/*.smv", recursive=True)
```

```python
def get_smv_file(path: str):
    """Get the .smv file in a given directory.

    :param path: Either the path to the directory containing the simulation data or direct path
        to the .smv file for the simulation in case that multiple simulation output was written to
        the same directory.
    """
    if os.path.isfile(path):
        return path
    elif os.path.isdir(path):
        files = scan_directory_smv(path)
        if len(files) > 1:
            raise IOError("There are multiple simulations in the directory: " + path)
        elif len(files) == 0:
            raise IOError("No simulations were found in the directory: " + path)
        return files[0]
    elif os.path.isfile(path + ".smv"):
        return path + ".smv"
    else:
        raise IOError("The given path does neither point to a directory nor a file: " + path)
```

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

### get_nearest_index(dimension, orientation, value)

Source: https://firedynamics.github.io/fdsreader/bndf.html

Gets the nearest mesh coordinate index.

```APIDOC
## get_nearest_index(dimension, orientation, value)

### Description
Get the nearest mesh coordinate index in a specific dimension for a specific orientation.
```

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

### Simulation Class Representation and Initialization

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Methods for defining the string representation and initializing the simulation object from a file path.

```python
def __getnewargs__(self):
    return self.smv_file_path,

def __repr__(self):
    r = f"Simulation(chid={self.chid},\n" + \
        f"           meshes={len(self.meshes)},\n" + \
        (f"           obstructions={len(self.obstructions)},\n" if len(self.obstructions) > 0 else "") + \
        (f"           geoms={len(self.geoms)},\n" if len(self.geoms) > 0 else "") + \
        (f"           slices={len(self.slices)},\n" if len(self.slices) > 0 else "") + \
        (f"           geomslices={len(self.geomslices)},\n" if len(self.geomslices) > 0 else "") + \
        (f"           data_3d={len(self.data_3d)},\n" if len(self.data_3d) > 0 else "") + \
        (f"           smoke_3d={len(self.smoke_3d)},\n" if len(self.smoke_3d) > 0 else "") + \
        (f"           isosurfaces={len(self.isosurfaces)},\n" if len(self.isosurfaces) > 0 else "") + \
        (f"           particles={len(self.particles)},\n" if len(self.particles) > 0 else "") + \
        (f"           evacs={len(self.evacs)},\n" if len(self.evacs) > 0 else "") + \
        (f"           devices={len(self.devices)},\n" if len(self.devices) > 0 else "")
    return r[:-2] + ')'

def __init__(self, path: str):
    """
    :param path: Either the path to the directory containing the simulation data or direct path
        to the .smv file for the simulation in case that multiple simulation output was written to
        the same directory.
    """
    if settings.IGNORE_ERRORS:
        warnings.filterwarnings("ignore")

    # Check if the file has already been instantiated via a cached pickle file
    if not hasattr(self, "_hash"):
        self.reader_version = __version__

        self.smv_file_path = get_smv_file(path)

        self.root_path = os.path.dirname(self.smv_file_path)

        self.geoms: List[Geometry] = list()
        self.surfaces: List[Surface] = list()
        self.ventilations = dict()

        # Will only be used during the loading process to map boundary data to the correct
        # obstruction
        self._subobstructions: Dict[str, List[SubObstruction]] = dict()

        # First collect all meta-information for any FDS data to later combine the gathered
        # information into data collections. While collecting the meta-data simple python
        # containers are used.
        self._obstructions = list()
        self._slices = dict()
        self._geomslices = dict()
        self.data_3d = Plot3DCollection([Plot3D(self.root_path) for _ in range(5)])
        self._smoke_3d = dict()
        self._isosurfaces = dict()
        self._particles = list()
        self._evacs = list()
        self._geom_data = list()
        self._meshes: List[Mesh] = list()
        self._devices = dict()

        self.profiles: Dict[str, Profile] = dict()

        self.parse_smv_file()

        self.cpu = self._load_CPU_data()
        self._load_profiles()

        # POST INIT (post read)
        self.out_file_path = os.path.join(self.root_path, self.chid + ".out")
        self.ventilations: List[Ventilation] = list(self.ventilations.values())

        for device_id, device in self._devices.items():
            if type(device) == list:
                for devc in device:
                    devc._data_callback = self._load_DEVC_data
            else:
                device._data_callback = self._load_DEVC_data
```

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

### SubObstruction.get_nearest_index

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Get the nearest mesh coordinate index in a specific dimension for a specific orientation.

```APIDOC
## get_nearest_index(dimension: Literal['x', 'y', 'z'], orientation: int, value: float) -> int

### Description
Get the nearest mesh coordinate index in a specific dimension for a specific orientation.

### Parameters
- **dimension** (Literal['x', 'y', 'z']) - Required - The dimension to search.
- **orientation** (int) - Required - The orientation index.
- **value** (float) - Required - The coordinate value to search for.
```

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

### Isosurface class initialization

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/isof/isosurface.html

Initializes the Isosurface container with metadata and quantity information.

```python
class Isosurface:
    """Isosurface file data container including metadata. Consists of a list of vertices forming a
        list of triangles. Can optionally have additional color data for the surfaces.

    :ivar id: The ID of this isosurface.
    :ivar quantity: Quantity object containing information about the quantity calculated for this
        isosurface with the corresponding short_name and unit.
    :ivar v_quantity: Information about the color quantity.
    :ivar levels: All isosurface levels.
    """

    def __init__(self, isosurface_id: int, double_quantity: bool, quantity: str,
                 short_name: str, unit: str, levels: List[float], v_quantity: str = "",
                 v_short_name: str = "", v_unit: str = ""):
        self.id = isosurface_id
        self.quantity = Quantity(quantity, short_name, unit)
        self._double_quantity = double_quantity
        self.levels = levels

        self._times = list()

        self._subsurfaces: Dict[str, SubSurface] = dict()

        if self._double_quantity:
            self.v_quantity = Quantity(v_quantity, v_short_name, v_unit)
```

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

### Initialize simulation data collections

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Aggregates temporary simulation data into specific collection objects and cleans up temporary attributes.

```python
# Combine the gathered temporary information into data collections
self.geom_data = GeometryCollection(self._geom_data)
self.slices = SliceCollection(
    Slice(self.root_path, slice_data[0]["id"], slice_data[0]["cell_centered"],
          slice_data[0]["times"], slice_data[1:]) for slice_data in self._slices.values())
self.geomslices = GeomSliceCollection(
    GeomSlice(self.root_path, slice_data[0]["id"],
              slice_data[0]["times"], slice_data[1:]) for slice_data in self._geomslices.values())
self.smoke_3d = Smoke3DCollection(self._smoke_3d.values())
self.isosurfaces = IsosurfaceCollection(self._isosurfaces.values())
self.devices = DeviceCollection(self._devices.values())
self.obstructions = ObstructionCollection(self._obstructions)
# If no particles are simulated, initialize empty data container for consistency
if type(self._particles) == list:
    self.particles = ParticleCollection((), ())
else:
    self.particles = self._particles
    self.particles._post_init()
# If no evacs are simulates, initialize empty data container for consistency
if len(self._evacs) == 0:
    self.evacs = EvacCollection((), "", ())
self.meshes = MeshCollection(self._meshes)
del self._geom_data, self._geomslices, self._slices, self._obstructions, self._smoke_3d, self._isosurfaces, self._devices, self._particles, self._evacs, self._meshes, self._subobstructions
```

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

### Get number of timesteps

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Retrieves the total number of timesteps, optionally including duplicates.

```python
def n_t(self, count_duplicates=True) -> int:
    """Get the number of timesteps for which data was output.
    :param count_duplicates: If true, return the total number of data points, even if there is
        duplicate data for a timestep. Duplicate data might be output when restarting the
        simulation in between the simulation run.
    """
    return self._patches[0].n_t(count_duplicates=count_duplicates)
```

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

### Get Nearest Index

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Finds the nearest mesh coordinate index for a specific dimension and orientation.

```python
def get_nearest_index(self, dimension: Literal['x', 'y', 'z'], orientation: int, value: float) -> int:
    """Get the nearest mesh coordinate index in a specific dimension for a specific orientation.
    """
    if self.has_boundary_data:
        coords = self.get_coordinates()[orientation][dimension]
        idx = np.searchsorted(coords, value, side="left")
        if idx > 0 and (idx == coords.size or np.math.fabs(value - coords[idx - 1]) < np.math.fabs(
                value - coords[idx])):
            return idx - 1
        else:
            return idx
    return np.nan
```

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

### fdsreader.simulation.Simulation

Source: https://firedynamics.github.io/fdsreader/simulation.html

Initializes the Simulation object by providing the path to the simulation directory or the .smv file.

```APIDOC
## class fdsreader.simulation.Simulation(path)

### Description
Master class managing all data for a given simulation.

### Parameters
- **path** (str) - Required - Either the path to the directory containing the simulation data or direct path to the .smv file for the simulation.
```

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

### Get Grid Values

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/fds_classes/mesh.html

Accesses all coordinate values for a specific dimension using index or axis name.

```python
    def __getitem__(self, dimension: Literal[0, 1, 2, 'x', 'y', 'z']) -> np.ndarray:
        """Get all values in given dimension.

        :param dimension: The dimension in which to return all grid values (0=x, 1=y, 2=z).
        """
        # Convert possible integer input to chars
        if type(dimension) == int:
            dimension = ('x', 'y', 'z')[dimension]
        return self.coordinates[dimension]
```

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

### Initialize Boundary object

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Constructor for the Boundary class.

```python
def __init__(self, quantity: Quantity, cell_centered: bool, times: Sequence[float], patches: List[Patch],
             lower_bounds: np.ndarray, upper_bounds: np.ndarray):
    self.quantity = quantity
    self.cell_centered = cell_centered
    self._patches = patches
    self.times = times
    self.lower_bounds = lower_bounds
    self.upper_bounds = upper_bounds
```

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

### Get Boundary Data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/fds_classes/mesh.html

Retrieves boundary data associated with a specific quantity name or short name.

```python
[docs]
    def get_boundary_data(self, quantity: Union[str, Quantity]):
        if type(quantity) == Quantity:
            quantity = quantity.name
        return next(b for b in self._boundary_data.values() if
                    b.quantity.name.lower() == quantity.lower() or b.quantity.short_name.lower() == quantity.lower())
```

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

### Enable simulation caching

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Saves the simulation state to a pickle file if caching is enabled in settings.

```python
if settings.ENABLE_CACHING:
    # Hash will be saved to simulation pickle file and compared to new hash when loading
    # the pickled simulation again in the next run of the program.
    self._hash = create_hash(self.smv_file_path)
    pickle.dump(self, open(Simulation._get_pickle_filename(self.root_path, self.chid), 'wb'), protocol=4)
```

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

### Get Nearest Coordinate

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/fds_classes/mesh.html

Finds the nearest point or cell center in the mesh grid for a given coordinate tuple.

```python
[docs]
    def get_nearest_coordinate(self, coordinate: Tuple[float, ...],
                            dimension: Tuple[Literal[1, 2, 3, 'x', 'y', 'z'], ...] = ('x', 'y', 'z'),
                            cell_centered=False) -> Tuple[float, ...]:
        """Finds the nearest point in the mesh's grid.

        :param coordinate: Tuple of 3 floats. If the dimension parameter is supplied, up to 2
            dimensions can be left out from the tuple.
        :param dimension: The dimensions in which to return the indices (1=x, 2=y, 3=z).
        :param cell_centered: Instead of finding the nearest point on the mesh, find the center of the nearest cell.
        """
        indices = self.coordinate_to_index(coordinate, dimension, cell_centered)
        ret = list()
        for i, dim in enumerate(dimension):
            coords = self.coordinates[dim]
            if cell_centered:
                coords = coords[:-1] + (coords[1] - coords[0]) / 2
            ret.append(coords[indices[i]])
        return tuple(ret)
```

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

### Load patch data from file

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Reads binary data from a file and reshapes it based on the patch dimensions.

```python
self._data = np.empty((self.n_t(count_duplicates=True),) + self.shape)
with open(self.file_path, 'rb') as infile:
    for t in range(self.n_t(count_duplicates=True)):
        infile.seek(self._initial_offset + self._patch_offset + t * self._time_offset)
        data = np.fromfile(infile, dtype_data, 1)[0][1].reshape(
            self.dimension.shape(cell_centered=False), order='F')
        if self.cell_centered:
            self._data[t, :] = data[:-1, :-1]
        else:
            self._data[t, :] = data
unique_times_indices = np.unique(self._boundary_parent.times, return_index=True)[1]
self._data = self._data[unique_times_indices]
return self._data
```

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

### Load boundary data from SMV file

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Parses boundary data from an SMV file pointer and associated binary files. Requires an open file handle and current line context.

```python
@log_error("bndf")
def _load_boundary_data(self, smv_file: TextIO, line: str, cell_centered: bool):
    """Loads the boundary data at current pointer position.
    """
    line = line.split()
    mesh_index = int(line[1]) - 1
    mesh = self._meshes[mesh_index]

    filename = smv_file.readline().strip()
    quantity = smv_file.readline().strip()
    short_name = smv_file.readline().strip()
    unit = smv_file.readline().strip()

    bid = int(filename.split('_')[-1][:-3]) - 1

    file_path = os.path.join(self.root_path, filename)

    patches = dict()
    mesh_patches = dict()

    if os.path.exists(file_path + ".bnd"):
        times = list()
        lower_bounds = list()
        upper_bounds = list()
        with open(file_path + ".bnd", 'r') as bnd_file:
            for line in bnd_file:
                splits = line.split()
                times.append(float(splits[0]))
                lower_bounds.append(float(splits[1]))
                upper_bounds.append(float(splits[2]))
        times = np.array(times)
        lower_bounds = np.array(lower_bounds, dtype=np.float32)
        upper_bounds = np.array(upper_bounds, dtype=np.float32)
        n_t = times.shape[0]
    else:
        times = None
        n_t = -1
        lower_bounds = np.array([0.0], dtype=np.float32)
        upper_bounds = np.array([np.float32(-1e33)], dtype=np.float32)

    with open(file_path, 'rb') as infile:
        # Offset of the binary file to the end of the file header.
        offset = 3 * fdtype.new((('c', 30),)).itemsize
        infile.seek(offset)

        n_patches = fdtype.read(infile, fdtype.INT, 1)[0][0][0]

        dtype_patches = fdtype.new((('i', 9),))
        patch_infos = fdtype.read(infile, dtype_patches, n_patches)
        offset += fdtype.INT.itemsize + dtype_patches.itemsize * n_patches
        patch_offset = fdtype.FLOAT.itemsize

        for patch_info in patch_infos:
            patch_info = patch_info[0]

            extent, dimension = self._indices_to_extent(patch_info[:6], mesh)
            orientation = patch_info[6]
            obst_index = patch_info[7] - 1

            p = Patch(file_path, dimension, extent, orientation, cell_centered,
                      patch_offset, offset, n_t, mesh)

            # "Obstacles" with index -1 give the extent of the (whole) mesh faces and refer to
            # "closed" mesh faces, therefore that data will be added to the corresponding mesh instead
            if obst_index != -1:
                if obst_index not in patches:
                    patches[obst_index] = list()
                patches[obst_index].append(p)
            else:
                if mesh.id not in mesh_patches:
                    mesh_patches[mesh.id] = list()
                mesh_patches[mesh.id].append(p)

            patch_offset += fdtype.new((('f', str(p.dimension.shape(cell_centered=False))),)).itemsize

    for obst_index, p in patches.items():
        for patch in p:
            patch._post_init(patch_offset)

        self._subobstructions[mesh.id][obst_index]._add_patches(bid, cell_centered, quantity,
                                                                short_name, unit, p, times,
                                                                lower_bounds, upper_bounds)

    for p in mesh_patches.values():
        for patch in p:
            patch._post_init(patch_offset)
        patch.mesh._add_patches(bid, cell_centered, quantity, short_name, unit, p, times,
                                lower_bounds, upper_bounds)
```

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

### Load Evacuation Data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Parses evacuation data files and initializes an EvacCollection.

```python
    @log_error("evac")
    def _load_evac_data(self, smv_file: TextIO, line: str):
        file_path = os.path.join(self.root_path, smv_file.readline().strip())

        mesh_index, z_offset = line.split()[1:]
        mesh = self._meshes[int(mesh_index) - 1]

        times = self._load_prt5_meta(self._evacs, file_path + '.bnd', mesh)[1:]  # First timestep is weird somehow
        if type(self._evacs) == list:
            self.evacs = EvacCollection(self._evacs, os.path.join(self.root_path, self.chid + "_evac"), times)

        self.evacs.z_offsets[mesh.id] = float(z_offset)
        self.evacs._file_paths[mesh.id] = file_path

        n_evacs = int(smv_file.readline().strip())
        for i in range(n_evacs):
            smv_file.readline()  # Skip "N" values
```

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

### Sort subslices in Cartesian coordinates

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/slcf/slice.html

Returns all subslices sorted based on their spatial orientation. Handles 3D-slices by inferring orientation from extent start points.

```python
def sort_subslices_cartesian(self):
    """Returns all subslices sorted in cartesian coordinates.
    """
    slices = list(self._subslices.values())
    slices_cart = [[slices[0]]]
    orientation = abs(slices[0].orientation)
    if orientation == 0:
        # 3D-slices have an orientation of 0, so we have to find the orientation ourself
        if slices[0].extent.x_start == slices[1].extent.x_start:
            orientation = 1
        elif slices[0].extent.y_start == slices[1].extent.y_start:
            orientation = 2
        elif slices[0].extent.z_start == slices[1].extent.z_start:
            orientation = 3

    if orientation == 1:  # x
        slices.sort(key=lambda p: (p.extent.y_start, p.extent.z_start))
    elif orientation == 2:  # y
        slices.sort(key=lambda p: (p.extent.x_start, p.extent.z_start))
    else:  # z
        slices.sort(key=lambda p: (p.extent.x_start, p.extent.y_start))

    # Form a list of lists (2D-array) of the sorted slices
    if orientation == 1:
        for slc in slices[1:]:
            if slc.extent.y_start == slices_cart[-1][-1].extent.y_start:
                slices_cart[-1].append(slc)
            else:
                slices_cart.append([slc])
    else:
        for slc in slices[1:]:
            if slc.extent.x_start == slices_cart[-1][-1].extent.x_start:
                slices_cart[-1].append(slc)
            else:
                slices_cart.append([slc])
    return slices_cart
```

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

### Load PRT5 Metadata

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Parses .bnd files to extract simulation timesteps and particle/evacuation bounds for a given mesh.

```python
    def _load_prt5_meta(self, prts: Union[List[Particle], ParticleCollection, List[Evacuation], EvacCollection],
                        file_path: str, mesh: Mesh) -> List[float]:
        is_evac = type(prts[0]) == Evacuation
        with open(file_path, 'r') as bnd_file:
            line = bnd_file.readline().strip().split()
            n_classes = int(line[1])
            times = list()
            n_quantities = list()
            for i in range(n_classes):
                line = bnd_file.readline().strip().split()
                n_quantities.append(int(line[0]))
                for _ in range(n_quantities[-1]):
                    bnd_file.readline()
                if is_evac:
                    prts[i].n_humans[mesh.id] = list()
                else:
                    prts[i].n_particles[mesh.id] = list()
            bnd_file.seek(0)

            for line in bnd_file:
                times.append(float(line.strip().split()[0]))
                for i in range(n_classes):
                    prt = prts[i]
                    n = int(bnd_file.readline().strip().split()[1].strip())
                    if is_evac:
                        prt.n_humans[mesh.id].append(n)
                    else:
                        prt.n_particles[mesh.id].append(n)
                    for q in range(n_quantities[i]):
                        line = bnd_file.readline().strip().split()
                        quantity = prt.quantities[q].name
                        prt.lower_bounds[quantity].append(float(line[0]))
                        prt.upper_bounds[quantity].append(float(line[1]))
        return times
```

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

### Load Particle Data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Processes particle data files and initializes a ParticleCollection.

```python
    @log_error("part")
    def _load_particle_data(self, smv_file: TextIO, line: str):
        file_path = os.path.join(self.root_path, smv_file.readline().strip())

        mesh_index = int(line.split()[1].strip()) - 1
        mesh = self._meshes[mesh_index]

        times = self._load_prt5_meta(self._particles, file_path + '.bnd', mesh)
        if type(self._particles) == list:
            self._particles = ParticleCollection(times, self._particles)

        self._particles._file_paths[mesh.id] = file_path

        n_classes = int(smv_file.readline().strip())
        for i in range(n_classes):
            smv_file.readline()  # Skip "N" values
```

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

### Initializing GeomSlice

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/slcf/geomslice.html

Constructor for the GeomSlice class, which aggregates data from multiple meshes.

```python
def __init__(self, root_path: str, geomslice_id: str, times: np.ndarray, multimesh_data: Collection[Dict]):
    self._root_path = root_path

    self.times = times

    if times is not None:
        self.n_t = times.size
    else:
        self.n_t = -1

    self.id = geomslice_id

    # List of all subgeomslices this geomslice consists of (one per mesh).
    self._subgeomslices: Dict[str, SubGeomSlice] = dict()

    vector_temp = dict()
    for mesh_data in multimesh_data:
        if "-VELOCITY" in mesh_data["quantity"]:
            vector_temp[mesh_data["mesh"].id] = dict()

    for mesh_data in multimesh_data:
        if mesh_data["mesh"].id not in self._subgeomslices:
            self.quantity = Quantity(mesh_data["quantity"], mesh_data["short_name"], mesh_data["unit"])
            self._subgeomslices[mesh_data["mesh"].id] = SubGeomSlice(self, mesh_data["filename"], mesh_data["geomfilename"], mesh_data["extent"], mesh_data["mesh"])
```

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

### Define Quantity and Profile data structures

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/utils/data.html

Classes for representing simulation quantities and profile data points.

```python
class Quantity:
    """Object containing information about a quantity with the corresponding short_name and unit.

    :ivar short_name: The short short_name representing the quantity.
    :ivar quantity: The name of the quantity.
    :ivar unit: The corresponding unit of the quantity.
    """
    def __init__(self, quantity: str, short_name: str, unit: str):
        self.short_name = short_name
        self.unit = unit
        self.name = quantity

    def __eq__(self, other):
        return self.name == other.name and self.short_name == other.short_name and self.unit == other.unit

    @property
    def quantity(self):
        return self.name

    @property
    def label(self):
        return self.short_name

    def __hash__(self):
        return hash(self.short_name)

    def __repr__(self):
        return f"Quantity('{self.name}')"
```

```python
class Profile:
    """Class containing profile data.
    """
    def __init__(self, profile_id: str, times: np.ndarray, npoints: np.ndarray, depths: np.ndarray, values: np.ndarray):
        self.id = profile_id
        self.times = times
        self.npoints = npoints
        self.depths = depths
        self.values = values

    def __eq__(self, other):
        return self.id == other.id

    def __repr__(self):
        return f"Profile(id='{self.id}', times={self.times}, depths={self.depths}, values={self.values})"
```

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

### Load Simulation Profiles

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Reads profile data files using numpy and stores them in the profiles dictionary.

```python
    @log_error("prof")
    def _load_profiles(self):
        for f in glob.glob(str(os.path.join(self.root_path, self.chid)) + "_prof*"):
            with open(f, 'r') as infile:
                profile_id = infile.readline()
                infile.readline()  # Skip header
                data: np.ndarray = np.genfromtxt(infile, delimiter=',', dtype=np.float32, autostrip=True).T
                times = data[0]
                npoints = data[1].astype(int)
                depths = np.empty((data.shape[1],), dtype=object)
                values = np.empty((data.shape[1],), dtype=object)

                for i, n in enumerate(npoints):
                    depths[i] = data[2: 2 + n, i]
                    values[i] = data[2 + n:, i]

                self.profiles[profile_id] = Profile(profile_id, times, npoints, depths, values)
```

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

### Load Mesh Data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Reads mesh configuration from an SMV file and calculates grid dimensions.

```python
def _load_mesh(self, smv_file: TextIO, line: str) -> Mesh:
    """Load information for a single mesh from the smv file at current pointer position.
    """
    mesh_id = "".join(line.split()[1:])

    grid_numbers = smv_file.readline().strip().split()
    grid_dimensions = {'x': int(grid_numbers[0]) + 1, 'y': int(grid_numbers[1]) + 1,
                       'z': int(grid_numbers[2]) + 1}
```

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

### vmin(quantity, orientation=0)

Source: https://firedynamics.github.io/fdsreader/bndf.html

Calculates the minimum value of all patches at any time for a specific quantity.

```APIDOC
## vmin(quantity: str | Quantity, orientation: int = 0) -> float

### Description
Minimum value of all patches at any time for a specific quantity.

### Parameters
- **quantity** (str | Quantity) - Required - The quantity to evaluate.
- **orientation** (int) - Optional - Optionally filter by patches with a specific orientation ({-3, -2, -1, 0, 1, 2, 3}).
```

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

### Visibility Management

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Methods to manage hide and show times for the obstruction.

```python
def _hide(self, time: float):
    self.hide_times.append(time)
    self.hide_times.sort()

def _show(self, time: float):
    self.show_times.append(time)
    self.show_times.sort()
```

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

### Calculate Boundary Min/Max Values

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/geom/geometry.html

Properties to retrieve the minimum and maximum values across all faces, with fallback logic for specific boundary conditions.

```python
@property
def vmin(self) -> float:
    """Minimum value of all faces at any time.
    """
    curr_min = min(np.min(b) for b in self.lower_bounds.values())
    if curr_min == 0.0:
        return min(min(np.min(p.data) for p in ps) for ps in self._faces.values())
    return curr_min

@property
def vmax(self) -> float:
    """Maximum value of all faces at any time.
    """
    curr_max = max(np.max(b) for b in self.upper_bounds.values())
    if curr_max == np.float32(-1e33):
        return max(max(np.max(p.data) for p in ps) for ps in self._faces.values())
    return curr_max
```

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

### Load Surface Information

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Parses surface properties from an SMV file at the current pointer position.

```python
@log_error("surface")
def _load_surface(self, smv_file: TextIO) -> Surface:
    """Load the information for a single surface from the smv file at current pointer position.
    """

    surface_id = smv_file.readline().strip()

    line = smv_file.readline().strip().split()
    tmpm, material_emissivity = float(line[0]), float(line[1])

    line = smv_file.readline().strip().split()

    surface_type = int(line[0])
    texture_width, texture_height = float(line[1]), float(line[2])
    rgb = (float(line[3]), float(line[4]), float(line[5]))
    transparency = float(line[6])

    texture_map = smv_file.readline().strip()
    texture_map = None if texture_map == "null" else os.path.join(self.root_path, texture_map)

    return Surface(surface_id, tmpm, material_emissivity, surface_type, texture_width,
                   texture_height, texture_map, rgb, transparency)
```

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

### Load Isosurface data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/simulation.html

Parses isosurface definitions and binary data levels.

```python
    @log_error("isof")
    def _load_isosurface(self, smv_file: TextIO, line: str):
        """Loads the isosurface at current pointer position.
        """
        double_quantity = line[0] == 'T'
        mesh_index = int(line.strip().split()[1]) - 1

        iso_filename = smv_file.readline().strip()
        iso_id = int(iso_filename.split('_')[-1][:-4])
        iso_file_path = os.path.join(self.root_path, iso_filename)

        if double_quantity:
            viso_file_path = os.path.join(self.root_path, smv_file.readline().strip())
        quantity = smv_file.readline().strip()
        short_name = smv_file.readline().strip()
        unit = smv_file.readline().strip()
        if double_quantity:
            v_quantity = smv_file.readline().strip()
            v_short_name = smv_file.readline().strip()
            v_unit = smv_file.readline().strip()

        if iso_id not in self._isosurfaces:
            with open(iso_file_path, 'rb') as infile:
                nlevels = fdtype.read(infile, fdtype.INT, 3)[2][0][0]

                dtype_header_levels = fdtype.new((('f', nlevels),))
                levels = fdtype.read(infile, dtype_header_levels, 1)[0]
        if double_quantity:
            if iso_id not in self._isosurfaces:
                self._isosurfaces[iso_id] = Isosurface(iso_id, double_quantity, quantity, short_name,
                                                       unit, levels, v_quantity=v_quantity,
                                                       v_short_name=v_short_name, v_unit=v_unit)
            self._isosurfaces[iso_id]._add_subsurface(self._meshes[mesh_index], iso_file_path,
                                                      viso_file_path=viso_file_path)
        else:
            if iso_id not in self._isosurfaces:
                self._isosurfaces[iso_id] = Isosurface(iso_id, double_quantity, quantity, short_name,
                                                       unit, levels)
            self._isosurfaces[iso_id]._add_subsurface(self._meshes[mesh_index], iso_file_path)
```

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

### Initialize Obstruction

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Constructor for the Obstruction class, defining geometry and appearance properties.

```python
def __init__(self, oid: str, color_index: int, block_type: int, texture_origin: Tuple[float, float, float],
             rgba: Union[Tuple[()], Tuple[float, float, float, float]] = ()):
    self.id = oid
    self.color_index = color_index
    self.block_type = block_type
    self.texture_origin = texture_origin
    if len(rgba) != 0:
        self.rgba = rgba

    self._subobstructions: Dict[str, SubObstruction] = dict()
```

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

### Retrieve minimum and maximum boundary values

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Methods to calculate the global minimum or maximum value across all patches for a specific quantity, optionally filtered by orientation.

```python
    def vmin(self, quantity: Union[str, Quantity], orientation: Literal[-3, -2, -1, 0, 1, 2, 3] = 0) -> float:
        """Minimum value of all patches at any time for a specific quantity.

        :param orientation: Optionally filter by patches with a specific orientation.
        """
        if self.has_boundary_data:
            return min(s.vmin(quantity, orientation) for s in self._subobstructions.values())
        else:
            return np.nan
```

```python
    def vmax(self, quantity: Union[str, Quantity], orientation: Literal[-3, -2, -1, 0, 1, 2, 3] = 0) -> float:
        """Maximum value of all patches at any time for a specific quantity.

        :param orientation: Optionally filter by patches with a specific orientation.
        """
        if self.has_boundary_data:
            return max(s.vmax(quantity, orientation) for s in self._subobstructions.values())
        return np.nan
```

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

### Load subsurface color data

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/isof/isosurface.html

Loads color data for all isosurfaces from a viso file.

```python
    def _load_vdata(self, infile: BinaryIO):
        """Loads all color data for all isosurfaces in a given viso file.
        """
        self._colors = np.empty((self.n_t,), dtype=object)
        dtype_nverts = fdtype.new((('i', 4),))

        infile.seek(fdtype.INT.itemsize * 2)
        t = fdtype.read(infile, fdtype.FLOAT, 1)
        while t.size != 0:
            time_index = self.times.index(t[0][0][0])
            n_vertices = fdtype.read(infile, dtype_nverts, 1)[0][0][2]
            if n_vertices > 0:
                self._colors[time_index] = fdtype.read(infile, fdtype.new((('f', n_vertices),)), 1)
            t = fdtype.read(infile, fdtype.FLOAT, 1)
```

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

### SubObstruction Initialization

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Initializes a SubObstruction instance with surfaces, bounds, extent, and mesh reference.

```python
def __init__(self, side_surfaces: Tuple, bound_indices: Tuple[int, int, int, int, int, int],
             extent: Extent, mesh: 'Mesh'):
    self.extent = extent
    self.side_surfaces = side_surfaces
    self.bound_indices = {'x': (bound_indices[0], bound_indices[1]),
                          'y': (bound_indices[2], bound_indices[3]),
                          'z': (bound_indices[4], bound_indices[5])}
    self.mesh = mesh

    self._boundary_data: Dict[int, Boundary] = dict()

    self.hide_times = list()
    self.show_times = list()
```

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

### export_smoke_raw(smoke3d, output_dir, ordering='C')

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/export/smoke3d_exporter.html

Exports 3D smoke data arrays to raw binary files and generates a corresponding .yaml metadata file.

```APIDOC
## export_smoke_raw

### Description
Exports the 3d arrays from a Smoke3D object to raw binary files with corresponding .yaml meta files.

### Parameters
- **smoke3d** (Smoke3D) - Required - The Smoke3D object to export.
- **output_dir** (str) - Required - The directory in which to save all files.
- **ordering** (Literal['C', 'F']) - Optional - Whether to write the data in C or Fortran ordering. Defaults to 'C'.
```

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

### Boundary.vmin

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/bndf/obstruction.html

Returns the minimum value of all patches at any time, optionally filtered by orientation.

```APIDOC
## vmin(orientation=0)

### Description
Returns the minimum value of all patches at any time.

### Parameters
- **orientation** (Literal[-3, -2, -1, 0, 1, 2, 3]) - Optional - Optionally filter by patches with a specific orientation.
```

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

### Mesh Class Definition and Initialization

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/fds_classes/mesh.html

Defines the Mesh class structure and initializes coordinate, dimension, and extent properties.

```python
from typing import Dict, Tuple, Sequence, List, Union
from typing_extensions import Literal
import numpy as np

from fdsreader import settings
from fdsreader.utils import Dimension, Extent, Quantity
from fdsreader.bndf import Boundary, Patch




[docs]
class Mesh:
    """3-dimensional Mesh of fixed, defined size.

    :ivar coordinates: Coordinate values for each of the 3 dimension.
    :ivar dimensions: :class:`Dimension` describing the size of the 3 dimensions regarding indices.
    :ivar extent: :class:`Extent` object containing 3-dimensional extent information.
    :ivar n: Number of elements for each of the 3 dimensions.
    :ivar n_size: Total number of blocks in this mesh.
    :ivar id: Mesh id/short_name assigned to this mesh.
    """

    def __init__(self, coordinates: Dict[Literal['x', 'y', 'z'], np.ndarray],
                 extents: Dict[Literal['x', 'y', 'z'], Tuple[float, float]], mesh_id: str):
        """
        :param coordinates: Coordinate values of the three axes.
        :param extents: Extent of the mesh in each dimension.
        :param mesh_id: ID of this mesh.
        """
        self.id = mesh_id
        self.coordinates = coordinates
        self.dimension = Dimension(
            coordinates['x'].size if coordinates['x'].size > 0 else 1,
            coordinates['y'].size if coordinates['y'].size > 0 else 1,
            coordinates['z'].size if coordinates['z'].size > 0 else 1)

        self.n_size = self.dimension.size()
        self.extent = Extent(extents['x'][0], extents['x'][1], extents['y'][0], extents['y'][1],
                             extents['z'][0], extents['z'][1])

        self.obstructions = list()

        self._boundary_data: Dict[int, Boundary] = dict()
```

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

### Calculate statistics and manage memory

Source: https://firedynamics.github.io/fdsreader/_modules/fdsreader/smoke3d/smoke3d.html

Methods for calculating global maximums, means, standard deviations, and clearing internal caches.

```python
@property
def vmax(self):
    """Maximum value of all data at any time.
    """
    curr_max = max(np.max(subsmoke3d.upper_bounds) for subsmoke3d in self._subsmokes.values())
    if curr_max == np.float32(-1e33):
        return max(np.max(subsmoke3d.data) for subsmoke3d in self._subsmokes.values())
    return curr_max

[docs]
@implements(np.mean)
def mean(self) -> np.ndarray:
    """Calculates the mean value of all Smoke3D data for this quantity.
    """
    return np.sum([np.mean(subsmoke.data) for subsmoke in self._subsmokes.values()]) / len(self._subsmokes)

[docs]
@implements(np.std)
def std(self) -> np.ndarray:
    """Calculates the standard deviation of all Smoke3D data for this quantity.
    """
    mean = self.mean
    sum = np.sum([np.sum(np.power(subsmoke.data - mean, 2)) for subsmoke in self._subsmokes.values()])
    N = np.sum([subsmoke.data.size for subsmoke in self._subsmokes.values()])
    return np.sqrt(sum / N)

[docs]
def clear_cache(self):
    """Remove all data from the internal cache that has been loaded so far to free memory.
    """
    for subsmoke in self._subsmokes.values():
        subsmoke.clear_cache()
```
Tokens:
Raw