API Reference

There are several key classes used by fiber assignment to load inputs, run the calculation, and write outputs. There are also some utility functions which are useful on their own.

High Level Interface

The operations performed by the command-line scripts described in Basic Tools simply call functions from the high-level interface to parse arguments and run the different steps. Here we will duplicate the examples in Basic Tools but do these interactively from a python session rather than calling scripts from the command line. Each of the command line operations is basically implemented by two functions: one to parse the arguments and one to run the code. When running interactively, you can use a small helper function to turn a dictionary of options into a list that can be passed to the parse functions:

fiberassign.utils.option_list(opts)[source]

Convert key, value pairs into a list.

This converts a dictionary into an options list that can be passed to ArgumentParser.parse_args(). The value for each dictionary key will be converted to a string. Values that are True will be assumed to not have a string argument added to the options list.

Parameters:: opts (dict) – Dictionary of options.
Returns:: The list of options.
Return type:: (list)

For running the fiber assignment for a survey, we parse options with:

fiberassign.scripts.assign.parse_assign(optlist=None)[source]

Parse assignment options.

This parses either sys.argv or a list of strings passed in. If passing an option list, you can create that more easily using the option_list() function.

Parameters:: optlist (list, optional) – Optional list of arguments to parse instead of using sys.argv.
Returns:: an ArgumentParser namespace.
Return type:: (namespace)

And then run the survey with one of two functions depending on how we are doing the assignment:

fiberassign.scripts.assign.run_assign_full(args, plate_radec=True)[source]

Run fiber assignment over all tiles simultaneously.

This uses the previously parsed options to read input data and run through the typical assignment sequence doing one step at a time over all tiles. It then writes to the outputs to disk.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

fiberassign.scripts.assign.run_assign_bytile(args)[source]

Run fiber assignment tile-by-tile.

This uses the previously parsed options to read input data and run through the typical assignment sequence on a single tile before moving on to the next. It then writes to the outputs to disk.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

EXAMPLE: Run the full assignment interactively:

from fiberassign.utils import option_list
from fiberassign.scripts.assign import (parse_assign, run_assign_full)

opts = {
    "targets": ["mtl.fits", "standards.fits", other.fits"],
    "write_all_targets": True,
    "dir": "out_raw"
}
optlist = option_list(opts)
args = parse_assign(optlist)
run_assign_full(args)

When merging results interactively, we can use the two functions:

fiberassign.scripts.merge.parse_merge(optlist=None)[source]

Parse merging options.

This parses either sys.argv or a list of strings passed in. If passing an option list, you can create that more easily using the option_list() function.

Parameters:: optlist (list, optional) – Optional list of arguments to parse instead of using sys.argv.
Returns:: an ArgumentParser namespace.
Return type:: (namespace)

fiberassign.scripts.merge.run_merge(args)[source]

Run output merging.

This uses the previously parsed options to read input data and perform merging of the input catalogs. This runs on one node and uses multiprocessing.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

EXAMPLE: Run the output merging interactively:

from fiberassign.utils import option_list
from fiberassign.scripts.merge import (parse_merge,
                                       run_merge)
opts = {
    "targets": ["mtl.fits", "standards.fits", other.fits"],
    "dir": "out_raw",
    "out": "out_merged"
}
optlist = option_list(opts)
args = parse_merge(optlist)
run_merge(args)

When running the QA interactively, we can use these functions:

fiberassign.scripts.qa.parse_qa(optlist=None)[source]

Parse QA options.

This parses either sys.argv or a list of strings passed in. If passing an option list, you can create that more easily using the option_list() function.

Parameters:: optlist (list, optional) – Optional list of arguments to parse instead of using sys.argv.
Returns:: an ArgumentParser namespace.
Return type:: (namespace)

fiberassign.scripts.qa.run_qa(args)[source]

Run QA.

This uses the previously parsed options to read input data and run the QA.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

EXAMPLE: Run the output merging interactively:

from fiberassign.utils import option_list
from fiberassign.scripts.qa import (parse_qa, run_qa)

opts = {
    "dir": "out_raw"
}
optlist = option_list(opts)
args = parse_qa(optlist)
run_qa(args)

When running the plotting interactively, these are the relevant functions:

fiberassign.scripts.plot.parse_plot(optlist=None)[source]

Parse plotting options.

This parses either sys.argv or a list of strings passed in. If passing an option list, you can create that more easily using the option_list() function.

Parameters:: optlist (list, optional) – Optional list of arguments to parse instead of using sys.argv.
Returns:: an ArgumentParser namespace.
Return type:: (namespace)

fiberassign.scripts.plot.run_plot(args)[source]

Run plotting of fiberassign outputs.

This uses the previously parsed options to read input data and make per-tile plots of the fiber assignment.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

EXAMPLE: Run the output merging interactively:

from fiberassign.utils import option_list
from fiberassign.scripts.plot import (parse_plot, run_plot)

opts = {
    "dir": "out_raw",
    "tiles": "plot_tiles.txt",
    "real_shapes": True
}
optlist = option_list(opts)
args = parse_plot(optlist)
run_plot(args)

And similarly when plotting the QA output:

fiberassign.scripts.qa_plot.parse_plot_qa(optlist=None)[source]

Parse QA plotting options.

This parses either sys.argv or a list of strings passed in. If passing an option list, you can create that more easily using the option_list() function.

Parameters:: optlist (list, optional) – Optional list of arguments to parse instead of using sys.argv.
Returns:: an ArgumentParser namespace.
Return type:: (namespace)

fiberassign.scripts.qa_plot.run_plot_qa(args)[source]

Run QA plotting.

This uses the previously parsed options to read input data and make a plot of the QA results.

Parameters:: args (namespace) – The parsed arguments.
Returns:: None

EXAMPLE: Run the output merging interactively:

from fiberassign.utils import option_list
from fiberassign.scripts.qa_plot import (parse_plot_qa,
                                         run_plot_qa)
opts = {
    "qafile": "out_raw/qa.json"
}
optlist = option_list(opts)
args = parse_plot_qa(optlist)
run_plot_qa(args)

Hardware Properties

All of the physical properties of the DESI instrument are contained in the Hardware class. Data from various files / sources must be read when constructing an instance of the Hardware class, so a helper function (load_hardware) is provided to make this easier. In the future, there will likely be even more instrument details contained in the Hardware class and we may need to move to using a config file or some other mechanism to pass all this information. Creating a hardware instance from Python should be done with this function:

fiberassign.hardware.load_hardware(focalplane=None, rundate=None, add_margins={}, get_time_range=False)[source]

Create a hardware class representing properties of the telescope.

Parameters:

focalplane (tuple) – Override the focalplane model. If not None, this should be a tuple of the same data types returned by desimodel.io.load_focalplane()
rundate (str) – ISO 8601 format time stamp as a string in the format YYYY-MM-DDTHH:MM:SS+-zz:zz. If None, uses current time.
add_margins (dict) – additional margins to add around positioners, GFAs, and petals. Dict with keys “pos”, “gfa”, “petal” and values of millimeters.
get_time_range (bool) – if True, return (hw, time_lo, time_hi), where time_lo and time_hi are datetime objects corresponding to the first and last dates when the hardware was in this state.

Returns:

(hardware, time_lo, time_hi) else: hardware

(Hardware): The hardware object.

Return type:

if get_time_range is True

Once loaded, there are a variety of public methods available in the Hardware class:

class fiberassign.hardware.Hardware

Class representing the hardware configuration of the telescope.

Parameters:

timestr (str) – ISO 8601 format time string in UTC.
location (array) – int32 array of location.
petal (array) – int32 array of petal index.
device (array) – int32 array of device number.
slitblock (array) – int32 array of slitblock.
blockfiber (array) – int32 array of blockfiber.
fiber (array) – int32 array of fiber IDs.
device_type (list) – List of strings of device types (e.g. POS, ETC).
x (array) – location X coordinate centers in mm.
y (array) – location Y coordinate centers in mm.
status (array) – array of integers containing the fiber status.
theta_offset (array) – The theta angle zero-points in degrees for each device.
theta_min (array) – The theta angle minimum value in degrees relative to the offset.
theta_max (array) – The theta angle maximum value in degrees relative to the offset.
theta_pos (array) – The current fixed theta position. Use to specify the position for stuck / broken positioners.
theta_arm (array) – The theta arm lengths in mm.
phi_offset (array) – The phi angle zero-points in degrees for each device.
phi_min (array) – The phi angle minimum value in degrees relative to the offset.
phi_max (array) – The phi angle maximum value in degrees relative to the offset.
phi_pos (array) – The current fixed phi position. Use to specify the position for stuck / broken positioners.
phi_arm (array) – The phi arm lengths in mm.
ps_radius (array) – The platescale radius vector in mm.
ps_theta (array) – The platescale theta vector in degrees.
arclen (array) – The radial arc length S(R) in mm.
excl_theta (list) – The Shape object for the exclusion polygon of the theta arm of each device.
excl_phi (list) – The Shape object for the exclusion polygon of the phi arm of each device.
excl_gfa (list) – The Shape object for the exclusion polygon of the GFA for each device.
excl_petal (list) – The Shape object for the exclusion polygon of the petal edge for each device.
added_margins (dict) – dict from string to float of margins that were added to the excl_ exclusion polygons. Elements could include ‘pos’ for positioners, ‘petal’ for overall petal, and ‘gfa’ for GFA chips.

property added_margins: Dictionary of additional margins that were added to exclusion polygons.

check_collisions_thetaphi(self: fiberassign._internal.Hardware, loc: collections.abc.Sequence[SupportsInt], theta: collections.abc.Sequence[SupportsFloat], phi: collections.abc.Sequence[SupportsFloat], threads: SupportsInt) → list[bool]

Check for collisions.

This takes the specified locations and computes the shapes of the central body and fiber holder when each fiber is moved to a given (theta, phi) orientation. It then tests for collisions between these shapes among the locations specified. The returned list of bools is True whenever the corresponding fiber had a collision and False otherwise.

Parameters:

loc (array) – List of locations.
theta (array) – Theta angle for each positioner.
phi (array) – Phi angle for each positioner.
threads (int) – If <= 0 use maximum threads, else use this number.

Returns:

A boolean value for each location.

Return type:

(list)

check_collisions_xy(self: fiberassign._internal.Hardware, loc: collections.abc.Sequence[SupportsInt], xy: collections.abc.Sequence[tuple[SupportsFloat, SupportsFloat]], threads: SupportsInt) → list[bool]

Check for collisions.

This takes the specified locations in the curved focal surface and computes the shapes of the central body and fiber holder when each fiber is moved to a given (X, Y) position. It then tests for collisions between these shapes among the locations specified. The returned list of bools is True whenever the corresponding fiber had a collision and False otherwise.

Parameters:

loc (list) – List of locations.
xy (list) – List of (X, Y) tuples at which to place each fiber.
threads (int) – If <= 0 use maximum threads, else use this number.

Returns:

A boolean value for each location.

Return type:

(list)

device_locations(self: fiberassign._internal.Hardware, type: str) → list[int]: Dictionary of locations for each device type (POS or ETC).

property focalplane_radius_deg: The focalplane radius in degrees.

property loc_blockfiber: Dictionary of blockfiber values for each location.

property loc_device: Dictionary of device ID for each location

property loc_device_type: Dictionary of device type (POS or ETC) for each location.

property loc_fiber: Dictionary of fiber values for each location.

property loc_gfa_excl: Dictionary of GFA exclusion shapes for each location.

property loc_petal: Dictionary of the petal for each location.

property loc_petal_excl: Dictionary of petal exclusion shapes for each location.

property loc_phi_arm: Dictionary of phi arm lengths for each location.

property loc_phi_excl: Dictionary of phi exclusion shapes for each location.

property loc_phi_max: Dictionary of phi max range from offset for each location.

property loc_phi_min: Dictionary of phi min range from offset for each location.

property loc_phi_offset: Dictionary of phi angle offsets for each location.

property loc_phi_pos: Dictionary of fixed phi positions for stuck / broken devices.

property loc_pos_cs5_mm: Dictionary of central (X, Y) position tuples for each location in CS5.

property loc_pos_curved_mm: Dictionary of central position tuples for each location in curved focal surface coordinates.

loc_position_thetaphi(self: fiberassign._internal.Hardware, loc: SupportsInt, theta: SupportsFloat, phi: SupportsFloat, shptheta: fiberassign._internal.Shape, shpphi: fiberassign._internal.Shape, ignore_range: bool = False) → bool

Move a positioner to a given set of theta / phi angles.

This takes the specified angles and computes the shapes of the central body and fiber holder when the fiber is moved to a the theta / phi orientation. The input shapes are modified in place.

Parameters:

loc (int) – Device location.
theta (float) – The theta angle.
phi (float) – The phi angle.
shptheta (Shape) – The theta shape.
shpphi (Shape) – The phi shape.
ignore_range=false (bool) – Ignore phi/theta min/max limits?

Returns:

None

loc_position_xy(self: fiberassign._internal.Hardware, id: SupportsInt, xy: tuple[SupportsFloat, SupportsFloat], shptheta: fiberassign._internal.Shape, shpphi: fiberassign._internal.Shape) → bool

Move a positioner to a given location.

This takes the specified location and computes the shapes of the central body and fiber holder when the fiber is moved to a given (X, Y) position in the curved focal surface. The input shapes are modified in place.

Parameters:

loc (int) – Device location.
xy (tuple) – The (X, Y) tuple at which to place the fiber.
shptheta (Shape) – The theta shape.
shpphi (Shape) – The phi shape.

Returns:

None

loc_position_xy_multi(self: fiberassign._internal.Hardware, loc: collections.abc.Sequence[SupportsInt], xy: collections.abc.Sequence[tuple[SupportsFloat, SupportsFloat]], threads: SupportsInt) → list[tuple[bool, tuple[fiberassign._internal.Shape, fiberassign._internal.Shape]]]

Move positioners to given locations.

This takes the specified locations and computes the shapes of the central body and fiber holder when each fiber is moved to a given (X, Y) position in the curved focal surface. The returned list of tuples contains the (central body, fiber holder) as 2 Shape objects for each location.

Parameters:

loc (list) – List of locations.
xy (list) – List of (X, Y) tuples at which to place each fiber.
threads (int) – If <= 0 use maximum threads, else use this number.

Returns:

One tuple for each location with positioner shapes.

Return type:

(list)

property loc_slitblock: Dictionary of slitblock values for each location.

property loc_theta_arm: Dictionary of theta arm lengths for each location.

property loc_theta_excl: Dictionary of theta exclusion shapes for each location.

property loc_theta_max: Dictionary of theta max range from offset for each location.

property loc_theta_min: Dictionary of theta min range from offset for each location.

property loc_theta_offset: Dictionary of theta angle offsets for each location.

property loc_theta_pos: Dictionary of fixed theta positions for stuck / broken devices.

property locations: Vector of locations.

property neighbor_radius_mm: Radius for considering locations as neighbors.

property neighbors: Dictionary of neighbor IDs for each location.

property nfiber_petal: The number of science positioners (device type POS) per petal.

property nloc: The number of device locations.

property npetal: The number of petals.

property patrol_buffer_mm: Buffer to subtract from full patrol radius when considering targets.

property petal_locations: Dictionary of the locations for each petal.

radial_ang2dist_CS5(self: fiberassign._internal.Hardware, theta_rad: SupportsFloat) → float

Covert the angle from the origin to CS5 distance in mm.

This uses the radial platescale to convert the angle to mm in the tangent plane (CS5) coordinates.

Parameters:: theta_rad (float) – Theta angle in radians.
Returns:: the distance in mm.
Return type:: (float)

radial_ang2dist_curved(self: fiberassign._internal.Hardware, theta_rad: SupportsFloat) → float

Covert the angle from the origin to curved focal surface distance in mm.

This uses the model S(R) arc length to convert the angle to mm in the curved focal surface.

Parameters:: theta_rad (float) – Theta angle in radians.
Returns:: the arc length distance in mm.
Return type:: (float)

radial_dist2ang_CS5(self: fiberassign._internal.Hardware, dist_mm: SupportsFloat) → float

Covert the CS5 distance from the origin in mm to an angle.

This uses the radial platescale to convert the distance in mm from the CS5 origin into an angle in radians.

Parameters:: dist_mm (float) – The distance in mm.
Returns:: the angle in radians.
Return type:: (float)

radial_dist2ang_curved(self: fiberassign._internal.Hardware, arc_mm: SupportsFloat) → float

Covert the curved focal surface distance from the origin in mm to an angle.

This uses the model S(R) arc length to convert distance in mm from the origin into an angle in radians.

Parameters:: arc_mm (float) – The arc length distance in mm.
Returns:: the angle in radians.
Return type:: (float)

property state: Dictionary of fiber state for each location.

thetaphi_to_xy(self: fiberassign._internal.Hardware, center: tuple[SupportsFloat, SupportsFloat], theta: SupportsFloat, phi: SupportsFloat, theta_arm: SupportsFloat, phi_arm: SupportsFloat, theta_zero: SupportsFloat, phi_zero: SupportsFloat, theta_min: SupportsFloat, phi_min: SupportsFloat, theta_max: SupportsFloat, phi_max: SupportsFloat, ignore_range: bool = False) → tuple

Compute the X / Y fiber location for positioner Theta / Phi angles.

Note that all X/Y calculations involving positioners are performed in the curved focal surface (NOT CS5).

Parameters:

center (tuple) – The (X, Y) tuple of the device center.
theta (float) – The positioner theta angle.
phi (float) – The positioner phi angle.
theta_arm (float) – The length of the theta arm.
phi_arm (float) – The length of the phi arm.
theta_zero (float) – The theta offset.
phi_zero (float) – The phi offset.
theta_min (float) – The theta min relative to the offset.
phi_min (float) – The phi min relative to the offset.
theta_max (float) – The theta max relative to the offset.
phi_max (float) – The phi max relative to the offset.
ignore_range=False (bool) – Ignore MIN/MAX_THETA/PHI and always return X,Y

Returns:

The X / Y location or (None, None) if the angles are: not valid for this positioner.

Return type:

(tuple)

time(self: fiberassign._internal.Hardware) → str

Return the time used when loading the focalplane model.

Returns:: the focalplane model time.
Return type:: (str)

xy_to_thetaphi(self: fiberassign._internal.Hardware, center: tuple[SupportsFloat, SupportsFloat], xy: tuple[SupportsFloat, SupportsFloat], theta_arm: SupportsFloat, phi_arm: SupportsFloat, theta_zero: SupportsFloat, phi_zero: SupportsFloat, theta_min: SupportsFloat, phi_min: SupportsFloat, theta_max: SupportsFloat, phi_max: SupportsFloat) → tuple

Compute the theta / phi arm angles when moved to an x / y point.

Note that all X/Y calculations involving positioners are performed in the curved focal surface (NOT CS5).

Parameters:

center (tuple) – The (X, Y) tuple of the device center.
xy (tuple) – The (X, Y) tuple at which to place the fiber.
theta_arm (float) – The length of the theta arm.
phi_arm (float) – The length of the phi arm.
theta_zero (float) – The theta offset.
phi_zero (float) – The phi offset.
theta_min (float) – The theta min relative to the offset.
phi_min (float) – The phi min relative to the offset.
theta_max (float) – The theta max relative to the offset.
phi_max (float) – The phi max relative to the offset.

Returns:

The theta / phi angles or (None, None) if the: x/y location is not reachable.

Return type:

(tuple)

Tile List (Survey Footprint)

The properties of the current pointings / tiles in use during assignment is stored in a Tiles instance. This just stores vectors of tile properties and the ordering of the tiles. For convenience, the load_tiles function should be used from Python to construct a Tiles object. This supports passing both a footprint (FITS format) file and also a list of tile IDs to select out of this larger footprint.

fiberassign.tiles.load_tiles(tiles_file=None, select=None, obstime=None, obstheta=None, obsha=None, obsthetacorr=False)[source]

Load tiles from a file.

Load tile data either from the specified file or from the default provided by desimodel. Optionally select a subset of tile IDs.

Parameters:

tiles_file (str) – Optional path to a FITS format footprint file.
select (list) – List of tile IDs to keep when reading the file.
obstime (str) – An ISO format string to override the observing time of all tiles.
obstheta (float) – The angle in degrees to override the field rotation of all tiles.
obsha (float) – The Hour Angle in degrees to design the observation of all tiles.
obsthetacorr (optional, defaults to False) – apply a correction on obstheta, based on DocDB-8931 (bool)

Returns:

A Tiles object.

Return type:

(Tiles)

Notes

2025, Feb.: added the obsthetacorr optional argument; this correction: implemented to avoid the hexapod rotation limit error, is presented/described in DocDB-8931.

Once created, the tile properties can be accessed directly from the Tiles object:

class fiberassign.tiles.Tiles

Class representing a sequence of tiles.

This is just a container of tile properties and mapping from tile ID to the order in the list.

Parameters:

ids (array) – array of int32 tile IDs.
ras (array) – array of float64 tile RA coordinates.
decs (array) – array of float64 tile DEC coordinates.
obs (array) – array of int32 obsconditions bitfields.
timeobs (list) – List of iso format datetime strings.
thetaobs (array) – Array of field rotation angles.
hourangobs (array) – Array of hour angles.

property dec: The array of tile DEC values.

property id: The array of tile IDs.

property obscond: The array of tile observing conditions values.

property obshourang: The array of tile observation hour angles.

property obstheta: The array of tile field rotation values.

property obstime: The array of tile observation times.

property order: Dictionary of tile index for each tile ID.

property ra: The array of tile RA values.

Target Catalogs

Target catalogs are loaded one at a time and a subset of their data is appended to a global dictionary of target properties. Targets in a catalog are assigned to one or more of the internal types (science, standard, sky, safe) based on the DESI_TARGET (or other column) value and either default or custom bitmasks.

Every science target is assigned an integer priority value prior to fiber assignment. This integer value is typically the same for objects of the same classification (“QSO”, “LRG”, “ELG”, etc). Sky targets effectively have a priority of zero. Each object is also assigned a random “subpriority” value, which is a double precision number. When two objects have the same integer priority value, the subpriority is used to indicate which object has a higher overall priority. Sky targets are also given a random subpriority value.

The target properties stored internally in fiberassign are found in the Target class for a single object:

class fiberassign.targets.Target

Class representing a single target.

property id: The target ID.

is_safe(self: fiberassign._internal.Target) → bool: Returns True if this is a safe target, else False.

is_science(self: fiberassign._internal.Target) → bool: Returns True if this is a science target, else False.

is_sky(self: fiberassign._internal.Target) → bool: Returns True if this is a sky target, else False.

is_standard(self: fiberassign._internal.Target) → bool: Returns True if this is a standard target, else False.

is_suppsky(self: fiberassign._internal.Target) → bool: Returns True if this is a suppsky target, else False.

property obsremain: The remaining observations for this target.

property priority: The integer priority class for this target.

property subpriority: The float64 subpriority on the range [0,1).

total_priority(self: fiberassign._internal.Target) → float: Return the total priority based on PRIORITY, SUBPRIORITY, and obs remaining.

property type: The internal target type (science, standard, sky, safe).

Before reading data, and empty Targets instance is created:

class fiberassign.targets.Targets

Class representing a list of targets.

The target data is stored internally as a dictionary of Target instances. After construction this container is empty, and then one uses the “append” method to add Targets.

append(self: fiberassign._internal.Targets, tsurvey: str, ids: collections.abc.Sequence[SupportsInt], obsremain: collections.abc.Sequence[SupportsInt], priority: collections.abc.Sequence[SupportsInt], subpriority: collections.abc.Sequence[SupportsFloat], type: collections.abc.Sequence[SupportsInt]) → None

Append objects to the target list.

Parameters:

survey (list) – the survey type of the target data.
ids (array) – array of int64 target IDs.
obsremain (array) – array of int32 number of remaining observations.
priority (array) – array of int32 values representing the target class priority for each object.
subpriority (array) – array of float64 values in [0.0, 1.0] representing the priority within the target class.
type (array) – array of uint8 bitfields holding the types of of each target (science, standard, etc).
survey – list of strings of the survey types for each target.

get(self: fiberassign._internal.Targets, id: SupportsInt) → fiberassign._internal.Target

Get the specified target.

Return a reference to the internal Target object with the specified ID.

Parameters:: id (int) – The target ID
Returns:: A target object.
Return type:: (Target)

get_priorities(self: fiberassign._internal.Targets, ids: collections.abc.Sequence[SupportsInt]) → numpy.typing.NDArray[numpy.int32]

Parameters:: ids (numpy array of ints) – The target IDs to look up
Returns:: numpy array (int32) of ‘priority’ values for those targets.

get_subpriorities(self: fiberassign._internal.Targets, ids: collections.abc.Sequence[SupportsInt]) → numpy.typing.NDArray[numpy.float64]

Parameters:: ids (numpy array of ints) – The target IDs to look up
Returns:: numpy array (double) of ‘subpriority’ values for those targets.

get_type_priority_subpriority(self: fiberassign._internal.Targets, ids: collections.abc.Sequence[SupportsInt]) → tuple

Parameters:: ids (numpy array of ints) – The target IDs to look up
Returns:: numpy array (uint8) of ‘type’ values for those targets. numpy array (int32) of ‘priority’ values for those targets. numpy array (double) of ‘subpriority’ values for those targets.
Return type:: tuple of

get_types(self: fiberassign._internal.Targets, ids: collections.abc.Sequence[SupportsInt]) → numpy.typing.NDArray[numpy.uint8]

Parameters:: ids (numpy array of ints) – The target IDs to look up
Returns:: numpy array (uint8) of ‘type’ values for those targets.

ids(self: fiberassign._internal.Targets) → numpy.typing.NDArray[numpy.int64]: Returns an array of all target IDs.

survey(self: fiberassign._internal.Targets) → str

Get the survey for the Targets object.

Returns:: The survey name.
Return type:: (str)

And then the load_target_file function is called one or more times to append target catalogs to the class instance.

fiberassign.targets.load_target_file(tgs, tagalong, tfile, survey=None, typeforce=None, typecol=None, sciencemask=None, stdmask=None, skymask=None, suppskymask=None, safemask=None, excludemask=None, rowbuffer=1000000, gaia_stdmask=None, rundate=None)[source]

Append targets from a file.

Read the specified file and append targets to the input Targets object. A subset of the columns in the file will be stored in each Target added to the Targets object. Each target is classified into one or more of the 4 types used internally in assignment (science, standard, sky, safe).

This classification is controlled by applying bitmasks to the specified data column. Alternatively, all targets in the file can be forced to one type.

Parameters:

tgs (Targets) – The targets object on which to append this data.
tagalong (TargetTagalong) – a data structure that carries RA,Dec, and other information for targets from the targeting files, to be written to the fiberassign outputs. A new one can be created using fiberassign.targets.create_tagalong.
tfile (str) – The path to the target catalog.
survey (str) – The survey type. If None, query from columns and the FITS header.
typeforce (int) – If specified, it must equal one of the TARGET_TYPE_* values. All targets read from the file will be assigned this type.
typecol (str) – Optional column to use for bitmask matching (default uses the result of main_cmx_or_sv from desitarget).
sciencemask (int) – Bitmask for classifying targets as science.
stdmask (int) – Bitmask for classifying targets as a standard.
skymask (int) – Bitmask for classifying targets as sky.
suppskymask (int) – Bitmask for classifying targets as suppsky.
safemask (int) – Bitmask for classifying targets as a safe location.
excludemask (int) – Bitmask for excluding targets.
rowbuffer (int) – Optional number of rows to read at once when loading very large files.
gaia_stdmask (int) – Bitmask for classifying targets as a Gaia standard.
rundate (optional, defaults to None) – yyyy-mm-ddThh:mm:ss+00:00 rundate for focalplane with UTC timezone formatting (string)

Returns:

The survey type.

Return type:

(str)

Notes

20210930 : include rundate argument, for default_main_stdmask().

After loading all the data, we build a scipy.spatial.KDTree to index these targets spatially for fast querying of targets that lie within some radius of a sky location.

Given a hardware model, our set of tiles, and this tree structure, we can now compute the target IDs available to every device location on every tile. This is done with the TargetsAvailable class:

class fiberassign.targets.TargetsAvailable

Class representing the objects reachable by each location of each tile.

This data structure makes it convenient and efficient to get the list of target IDs available to a given location for a given tile.

Parameters:

hw (Hardware) – The hardware model.
objs (Targets) – The Targets.
tiles (Tiles) – The tiles to consider.
tree (TargetTree) – The HTM tree of object positions.

hardware(self: fiberassign._internal.TargetsAvailable) → fiberassign._internal.Hardware: Return a handle to the Hardware object used.

tile_data(self: fiberassign._internal.TargetsAvailable, tile: SupportsInt) → dict[int, list[int]]

Return the targets available for a given tile.

This returns a copy of the internal C++ available targets for a given tile ID. The returned data is a dictionary with the location as the key and the value is an array of target IDs available to the location.

Parameters:: tile (int) – The tile ID.
Returns:: Dictionary of available targets for each location.
Return type:: (dict)

tiles(self: fiberassign._internal.TargetsAvailable) → fiberassign._internal.Tiles: Return a handle to the Tiles object used.

We can also compute the inverse quantity: the tile-location combinations that can reach each target ID. This is done with the LocationsAvailable class:

class fiberassign.targets.LocationsAvailable

Class representing the tile/location reachable by each target.

This data structure makes it convenient and efficient to get the list of tile / location pairs that can reach a given target.

Parameters:: tgsavail (TargetsAvailable) – the targets available to each location.

target_data(self: fiberassign._internal.LocationsAvailable, target: SupportsInt) → list[tuple[int, int]]

Return the tile/loc pairs that can reach a target.

This returns a copy of the internal C++ data. The return value is a list of tuples containing the (tile ID, location) pairs that can reach the specified target ID.

Parameters:: target (int) – The target ID.
Returns:: List of (tile, loc) tuples.
Return type:: (list)

Assignment

The Assignment class is what drives the overall assignment process. The algorithms of these functions are described below. See the documentation for the individual methods for the mechanics of using them.

Assigning Targets to Unused Fibers

When assigning a particular class of target (“science”, “standard”, or “sky”) to unused locations, the same technique (and code) is used.

Todo

Algorithm discussion here, once relevant github issues and their associated changes are done.

Redistributing Science Targets

Todo

Algorithm discussion here once relevant github issues and their associated changes are done.

Forced Assignment of Standards and Sky

When calling this method, our goal is to displace science targets with either standards or sky targets in order to meet some required number per petal. For each petal, we rank the available objects of interest (standards or sky) by total priority (priority + subpriority). We also identify all science target priority values across the whole fiber assignment run and sort these from lowest to highest.

For each petal, we do the following pseudocode:

for each science target priority "P" (lowest to highest)
    for each object (standard or sky) in total priority from high to low
        if object is reachable by devices on targets with priority "P"
            remove target and place positioner on object
            re-assign target to unused location on future tile if possible
            if enough objects on this petal
                break

Note

This algorithm may be changed slightly in the near future. See open github tickets for latest developments.

class fiberassign.assign.Assignment

Class representing the current assignment of all locations.

This data structure stores the current location assignment and provides methods for manipulating that assignment

Parameters:

tgs (Targets) – the targets.
tgsavail (TargetsAvailable) – the targets available to each location.
locavail (LocationsAvailable) – the locations available to each target.

assign_force(self: fiberassign._internal.Assignment, tgtype: SupportsInt = 1, required_per_petal: SupportsInt = 0, required_per_slitblock: SupportsInt = 0, start_tile: SupportsInt = -1, stop_tile: SupportsInt = -1) → None

Force assignment of targets to unused locations.

This function will “bump” science targets (starting with lowest priority) in order to place the required number of targets of the specified type on each petal.

Parameters:

tgtype (int) – The target type to assign, which must be one of the predefined TARGET_TYPE_* module attributes.
required_per_petal (int) – Bump science targets until this limit is reached.
required_per_slitblock (int) – Bump science targets until this limit is reached.
start_tile (int) – Start assignment at this tile ID in the sequence of tiles.
stop_tile (int) – Stop assignment at this tile ID (inclusive) in the sequence of tiles.

Returns:

None

assign_unused(self: fiberassign._internal.Assignment, tgtype: SupportsInt = 1, max_per_petal: SupportsInt = -1, max_per_slitblock: SupportsInt = -1, pos_type: str = 'POS', start_tile: SupportsInt = -1, stop_tile: SupportsInt = -1, use_zero_obsremain: bool = False) → None

Assign targets to unused locations.

This will attempt to assign targets of the specified type to unused locations with devices of the specified type.

Parameters:

tgtype (int) – The target type to assign, which must be one of the predefined TARGET_TYPE_* module attributes.
max_per_petal (int) – Limit the assignment to this many objects per petal. Default is no limit.
max_per_slitblock (int) – Limit the assignment to this many objects per slitblock. Default is no limit.
pos_type (str) – Only consider this positioner device type. Default is “POS”.
start_tile (int) – Start assignment at this tile ID in the sequence of tiles.
stop_tile (int) – Stop assignment at this tile ID (inclusive) in the sequence of tiles.
use_zero_obsremain (bool) – If True, and tgtype is science targets, then consider science targets with < 1 observation remaining.

Returns:

None

check_avail_collisions(self: fiberassign._internal.Assignment, tile: SupportsInt, all_matches: bool = False) → dict[tuple[int, int], int]

Return a bitmask describing the collisions for each potential assignment for a given tile.

This returns a dict from (LOCID, TARGETID) to a bitmask:: 1: BROKEN or STUCK positioner 2: collision with STUCK positioner 4: collision with GFA or petal edge

Parameters:

tile (int) – The tile ID.
all_matches (bool, default False) – If True, returns the bitmask (including zeros) for all entries; otherwise, only return non-zero entries.

Returns:

Dictionary from (LOCID, TARGETID) to collision bitmask.

Return type:

(dict)

get_counts(self: fiberassign._internal.Assignment, arg0: SupportsInt, arg1: SupportsInt) → dict[int, dict[str, int]]: Returns a summary of counts of assignments per target class. Return value is a dict: tile_id -> dict( type -> count ).

hardware(self: fiberassign._internal.Assignment) → fiberassign._internal.Hardware: Return a handle to the Hardware object used.

locations_avail(self: fiberassign._internal.Assignment) → fiberassign._internal.LocationsAvailable: Return a handle to the LocationsAvailable object used.

redistribute_science(self: fiberassign._internal.Assignment, start_tile: SupportsInt = -1, stop_tile: SupportsInt = -1) → None

Redistribute science targets to future tiles.

This function attempts to load balance the science targets per petal by moving science target to future available tile/loc placements that lie on petals with fewer total science targets.

Parameters:

start_tile (int) – Start assignment at this tile ID in the sequence of tiles.
stop_tile (int) – Stop assignment at this tile ID (inclusive) in the sequence of tiles.

Returns:

None

targets(self: fiberassign._internal.Assignment) → fiberassign._internal.Targets: Return a handle to the Targets object used.

targets_avail(self: fiberassign._internal.Assignment) → fiberassign._internal.TargetsAvailable: Return a handle to the TargetsAvailable object used.

tile_location_target(self: fiberassign._internal.Assignment, tile: SupportsInt) → dict[int, int]

Return the assignment for a given tile.

This returns a copy of the internal C++ target assignment for a given tile ID. The returned data is a dictionary with the location as the key and the value is the assigned target ID. Only assigned locations are stored. Unassigned locations do not exist in this dictionary.

Parameters:: tile (int) – The tile ID.
Returns:: Dictionary of assigned target for each location.
Return type:: (dict)

tiles(self: fiberassign._internal.Assignment) → fiberassign._internal.Tiles: Return a handle to the Tiles object used.

tiles_assigned(self: fiberassign._internal.Assignment) → list[int]: Return an array of currently assigned tile IDs.

Visualization and I/O

Utilities

The fiberassign package includes a number of useful math and helper functions.

Geometric Shapes

The geometry of the positioners is represented internally as a shape consisting of line segments and circles.

class fiberassign.utils.Circle

A Circle.

This class represents a circle with a center and radius. This shape can be translated and rotated about an axis.

Parameters:

center (tuple) – The (X, Y) center of the circle.
radius (float) – The radius of the circle.

property center: The center (X, Y) tuple of the circle.

property radius: The radius of the circle.

rotation(self: fiberassign._internal.Circle, angle: tuple[SupportsFloat, SupportsFloat], axis: tuple[SupportsFloat, SupportsFloat]) → None

Apply a rotation.

Rotate the circle center by an angle about the given point.

Parameters:

angle (float) – The angle of rotation.
axis (tuple) – The (X, Y) origin of the rotation.

transl(self: fiberassign._internal.Circle, offset: tuple[SupportsFloat, SupportsFloat]) → None

Translate the circle.

Parameters:: offset (tuple) – The (X, Y) offset to add to the center.

class fiberassign.utils.Segments

A collection of line segments.

This class represents a sequence of connected line segments.

Parameters:: points (list) – A list of (X, Y) tuples containing the points describing the segments.

property points: The list of points.

rotation(self: fiberassign._internal.Segments, angle: tuple[SupportsFloat, SupportsFloat], axis: tuple[SupportsFloat, SupportsFloat]) → None

Apply a rotation.

Rotate all points by an angle about the given origin.

Parameters:

angle (float) – The angle of rotation.
axis (tuple) – The (X, Y) origin of the rotation.

transl(self: fiberassign._internal.Segments, offset: tuple[SupportsFloat, SupportsFloat]) → None

Translate the segments.

Parameters:: offset (tuple) – The (X, Y) offset to add to all points.

class fiberassign.utils.Shape

A shape made up of circles and segments.

A Shape contains a list Circle objects and a list of Segments objects that can be rotated / translated together. Each shape also has a center point independent of the individual pieces.

Parameters: