LaPDXYExclusion

class bapsf_motion.motion_builder.exclusions.lapd.LaPDXYExclusion(ds: Dataset, *, diameter: float = 100, pivot_radius: float = 58.771, port_location: str | float = 'E', cone_full_angle: float = 58, include_cone: bool = True, skip_ds_add: bool = False)

Bases: GovernExclusion

Class for defining the :term`LaPD` exclusion layer in a XY motion space. This class setups up the typical XY exclusion layer for a probe installed on a LaPD ball valve.

exclusion type: 'lapd_xy'

Parameters:

ds (DataSet) – The xarray Dataset the motion builder configuration is constructed in.
diameter (Real) – Diameter of the LaPD chamber. (DEFAULT: 100)
pivot_radius (Real) – Distance from the ball valve pivot point to the LaPD center axis. (DEFAULT: 58.771)
port_location (Union[str, Real]) – A variable indicating which port the probe is located at. A value can be a string of \(\in\) \(\{\)e, east, t, top, w, west, b, bot, bottom\(\}\) (case-insensitive) or an angle \(\in [0,360)\). An East port would correspond to an angle of 0 and a Top port corresponds to an angle of 90. An angle port can be indicated by using the corresponding angle, e.g. 45. (DEFAULT: 'E')
cone_full_angle (Real) – The full angle of range provided by the ball valve. (DEFAULT: 80)
include_cone (bool) – If True, then include the exclusion created by the ball valve limits. Otherwise, False will only include the chamber wall exclusion. (DEFAULT: True)
skip_ds_add (bool) – If True, then skip generating the DataArray corresponding to the exclusion layer and skip adding it to the Dataset. (DEFAULT: False)

Examples

Note

The following examples include examples for direct instantiation, as well as configuration passing at the MotionGroup and RunManager levels.

Assume we have a 2D motion space and want to create the default exclusion for a probe deployed on the East port. This would look like:

el = LaPDXYExclusion(ds)

el = exclusion_factory(
    ds,
    ex_type = "lapd_xy",
)

[...motion_builder.exclusions]
type = "lapd_xy"

config["motion_builder"]["exclusions"] = {
    "type": "lapd_xy",
}

Now, lets deploy a probe on a West port using a ball valve with a narrower cone and a more restrictive chamber diameters.

el = LaPDXYExclusion(
    ds,
    diameter = 60,
    port_location = "W",
    cone_full_angle = 60,
)

el = exclusion_factory(
    ds,
    ex_type = "lapd_xy",
    **{
        "diameter": 60,
        "port_location": "W",
        "cone_full_angle": 60,
    },
)

[...motion_builder.exclusions]
type = "lapd_xy"
diameter = 60
port_location = "W"
cone_full_angle = 60

config["motion_builder"]["exclusions"] = {
    "type": "lapd_xy",
    "diameter": 60,
    "port_location": "W",
    "cone_full_angle": 60,
}

Attributes Summary

`base_name`	Base name for associated items in the `Dataset`.
`cone_full_angle`	Full angle of range allowed by the ball valve.
`config`	Dictionary containing the full configuration of the motion exclusion.
`diameter`	Diameter of the LaPD chamber.
`dimensionality`	The designed dimensionality of the exclusion layer.
`exclusion`	The `DataArray` associate with the exclusion.
`exclusion_type`	String naming the motion exclusion type.
`include_cone`	`True` if the ball valve angle is added to the exclusion, `False` otherwise.
`inputs`	A dictionary of the configuration inputs passed during layer instantiation.
`insertion_point`	(X, Y) location of the pivot, probe-insertion point.
`item`	The representative motion builder item in the `Dataset`.
`mask`	A \(N\)-D `DataArray` representing a boolean mask of the motion space.
`mask_name`	Name of the `mask` item it the `Dataset`.
`mask_resolution`	Tuple containing the spatial resolution of each dimension of the motion space (i.e. grid spacing in each dimension).
`mspace_coords`	Dictionary-like container of motion space coordinates.
`mspace_dims`	Tuple of motion space dimension names.
`mspace_ndims`	Dimensionality of the motion space.
`name`	Name of the motion builder item in the `Dataset`.
`name_pattern`	The naming pattern for motion builder items in the `Dataset`.
`pivot_radius`	Distance from the ball valve pivot to the chamber center axis.
`port_location`	Angle [in degrees] corresponding to the port location the probe is deployed on.
`composed_exclusions`	Dictionary of dependent motion exclusions used to make this more complex motion exclusion.

Methods Summary

`drop_vars`(names, *[, errors])	Drop variables from this dataset.
`is_excluded`(point)	Check if `point` resides in an excluded region defined by this motion exclusion.
`regenerate_exclusion`()	Re-generate the motion exclusion, i.e. `exclusion`.
`update_global_mask`()	Update the global `mask` to include the exclusions from this exclusion layer.

Attributes Documentation

base_name: Base name for associated items in the Dataset.

cone_full_angle: Full angle of range allowed by the ball valve.

config: Dictionary containing the full configuration of the motion exclusion.

diameter: Diameter of the LaPD chamber.

dimensionality: The designed dimensionality of the exclusion layer. If -1, then the exclusion does not have a fixed dimensionality, and it can morph to the associated motion space.

exclusion

The DataArray associate with the exclusion. If the exclusion layer has not been generated, then it will be done automatically.

An exclusion DataArray is a boolean array the behaves like a mask to define where a probe can and can not be placed.

exclusion_type: String naming the motion exclusion type. This is unique among all subclasses of BaseExclusion.

include_cone: True if the ball valve angle is added to the exclusion, False otherwise.

inputs: A dictionary of the configuration inputs passed during layer instantiation.

insertion_point: (X, Y) location of the pivot, probe-insertion point.

item: The representative motion builder item in the Dataset.

mask: A \(N\)-D DataArray representing a boolean mask of the motion space. The mask is True where a probe drive is allowed to move, and False otherwise.

mask_name: Name of the mask item it the Dataset.

mask_resolution: Tuple containing the spatial resolution of each dimension of the motion space (i.e. grid spacing in each dimension).

mspace_coords: Dictionary-like container of motion space coordinates. Keys are given by mspace_dims. Quick access to coords of mask.

mspace_dims: Tuple of motion space dimension names. Quick access to dims of mask.

mspace_ndims: Dimensionality of the motion space. Synonymous with the number of axes of the probe drive.

name: Name of the motion builder item in the Dataset.

name_pattern: The naming pattern for motion builder items in the Dataset.

pivot_radius: Distance from the ball valve pivot to the chamber center axis.

port_location: Angle [in degrees] corresponding to the port location the probe is deployed on. An angle of 0 corresponds to the East port and 90 corresponds to the Top port.

composed_exclusions: Dict[str, BaseExclusion]: Dictionary of dependent motion exclusions used to make this more complex motion exclusion.

Methods Documentation

drop_vars(names: str, *, errors: Literal['raise', 'ignore'] = 'raise')

Drop variables from this dataset.

Parameters:

names (Hashable or iterable of Hashable or Callable) – Name(s) of variables to drop. If a Callable, this object is passed as its only argument and its result is used.
errors ({"raise", "ignore"}, default: "raise") – If ‘raise’, raises a ValueError error if any of the variable passed are not in the dataset. If ‘ignore’, any given names that are in the dataset are dropped and no error is raised.

Examples

>>> dataset = xr.Dataset(
...     {
...         "temperature": (
...             ["time", "latitude", "longitude"],
...             [[[25.5, 26.3], [27.1, 28.0]]],
...         ),
...         "humidity": (
...             ["time", "latitude", "longitude"],
...             [[[65.0, 63.8], [58.2, 59.6]]],
...         ),
...         "wind_speed": (
...             ["time", "latitude", "longitude"],
...             [[[10.2, 8.5], [12.1, 9.8]]],
...         ),
...     },
...     coords={
...         "time": pd.date_range("2023-07-01", periods=1),
...         "latitude": [40.0, 40.2],
...         "longitude": [-75.0, -74.8],
...     },
... )
>>> dataset
<xarray.Dataset> Size: 136B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop the ‘humidity’ variable

>>> dataset.drop_vars(["humidity"])
<xarray.Dataset> Size: 104B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop the ‘humidity’, ‘temperature’ variables

>>> dataset.drop_vars(["humidity", "temperature"])
<xarray.Dataset> Size: 72B
Dimensions:     (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time        (time) datetime64[us] 8B 2023-07-01
  * latitude    (latitude) float64 16B 40.0 40.2
  * longitude   (longitude) float64 16B -75.0 -74.8
Data variables:
    wind_speed  (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Drop all indexes

>>> dataset.drop_vars(lambda x: x.indexes)
<xarray.Dataset> Size: 96B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Dimensions without coordinates: time, latitude, longitude
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Attempt to drop non-existent variable with errors=”ignore”

>>> dataset.drop_vars(["pressure"], errors="ignore")
<xarray.Dataset> Size: 136B
Dimensions:      (time: 1, latitude: 2, longitude: 2)
Coordinates:
  * time         (time) datetime64[us] 8B 2023-07-01
  * latitude     (latitude) float64 16B 40.0 40.2
  * longitude    (longitude) float64 16B -75.0 -74.8
Data variables:
    temperature  (time, latitude, longitude) float64 32B 25.5 26.3 27.1 28.0
    humidity     (time, latitude, longitude) float64 32B 65.0 63.8 58.2 59.6
    wind_speed   (time, latitude, longitude) float64 32B 10.2 8.5 12.1 9.8

Attempt to drop non-existent variable with errors=”raise”

>>> dataset.drop_vars(["pressure"], errors="raise")
Traceback (most recent call last):
ValueError: These variables cannot be found in this dataset: ['pressure']

Raises:: ValueError – Raised if you attempt to drop a variable which is not present, and the kwarg errors='raise'.
Returns:: dropped
Return type:: Dataset