Utilities#

In this section you find the reference documentation of the modules contained in the util module.

general#

General functions useful across different parts of the code.

utils.general.change_dict_keys_case(data_dict, lower_case=True)[source]#

Change keys of a dictionary to lower or upper case recursively.

Parameters:
data_dict: dict

Dictionary to be converted.

lower_case: bool

Change keys to lower (upper) case if True (False).

Returns:
dict

Dictionary with keys converted to lower or upper case.

utils.general.clear_default_sim_telarray_cfg_directories(command)[source]#

Prefix the command to clear default sim_telarray configuration directories.

Parameters:
command: str

Command to be prefixed.

Returns:
str

Prefixed command.

utils.general.collect_final_lines(file, n_lines)[source]#

Collect final lines.

Parameters:
file: str or Path

File to collect the lines from.

n_lines: int

Number of lines to be collected.

Returns:
str

Final lines collected.

utils.general.collect_kwargs(label, in_kwargs)[source]#

Collect kwargs of the type label_* and return them as a dict.

Parameters:
label: str

Label to be collected in kwargs.

in_kwargs: dict

kwargs.

Returns:
dict

Dictionary with the collected kwargs.

utils.general.get_log_excerpt(log_file, n_last_lines=30)[source]#

Get an excerpt from a log file, namely the n_last_lines of the file.

Parameters:
log_file: str or Path

Log file to get the excerpt from.

n_last_lines: int

Number of last lines of the file to get.

Returns:
str

Excerpt from log file with header/footer

utils.general.get_log_level_from_user(log_level)[source]#

Map between logging level from the user to logging levels of the logging module.

Parameters:
log_level: str

Log level from the user.

Returns:
logging.LEVEL

The requested logging level to be used as input to logging.setLevel().

utils.general.remove_substring_recursively_from_dict(data_dict, substring='\n')[source]#

Remove substrings from all strings in a dictionary.

Recursively crawls through the dictionary This e.g., allows to remove all newline characters from a dictionary.

Parameters:
data_dict: dict

Dictionary to be converted.

substring: str

Substring to be removed.

Raises:
AttributeError:

if input is not a proper dictionary.

utils.general.set_default_kwargs(in_kwargs, **kwargs)[source]#

Fill in a dict with a set of default kwargs and return it.

Parameters:
in_kwargs: dict

Input dict to be filled in with the default kwargs.

**kwargs:

Default kwargs to be set.

Returns:
dict

Dictionary containing the default kwargs.

geometry#

A collection of functions related to geometrical transformations.

utils.geometry.convert_2d_to_radial_distr(hist_2d, xaxis, yaxis, bins=50, max_dist=1000)[source]#

Convert a 2d histogram of positions, e.g. photon positions on the ground, to a 1D distribution.

Parameters:
hist_2d: numpy.ndarray

The histogram counts.

xaxis: numpy.array

The values of the x axis (histogram bin edges) on the ground.

yaxis: numpy.array

The values of the y axis (histogram bin edges) on the ground.

bins: float

Number of bins in distance.

max_dist: float

Maximum distance to consider in the 1D histogram, usually in meters.

Returns:
np.array

The values of the 1D histogram with size = int(max_dist/bin_size).

np.array

The bin edges of the 1D histogram with size = int(max_dist/bin_size) + 1.

utils.geometry.rotate(x, y, rotation_around_z_axis, rotation_around_y_axis=0)[source]#

Rotate the x and y coordinates of the telescopes.

The two rotations are:

  • rotation_angle_around_z_axis gives the rotation on the observation plane (x, y)

  • rotation_angle_around_y_axis allows to rotate the observation plane in space.

The function returns the rotated x and y values in the same unit given. The direction of rotation of the elements in the plane is counterclockwise, i.e., the rotation of the coordinate system is clockwise.

Parameters:
x: numpy.array or list

x positions of the entries (e.g. telescopes), usually in meters.

y: numpy.array or list

y positions of the entries (e.g. telescopes), usually in meters.

rotation_angle_around_z_axis: astropy.units.rad

Angle to rotate the array in the observation plane (around z axis) in radians.

rotation_angle_around_y_axis: astropy.units.rad

Angle to rotate the observation plane around the y axis in radians.

Returns:
2-tuple of list

x and y positions of the rotated entry (e.g. telescopes) positions.

Raises:
TypeError:

If type of x and y parameters are not valid.

RuntimeError:

If the length of x and y are different.

UnitsError:

If the unit of x and y are different.

names#

Name utilities for array elements, sites, and model parameters.

Naming in simtools:

  • ‘site’: South or North

  • ‘array element’: e.g., LSTN-01, MSTN-01, …

  • ‘array element type’: e.g., LSTN, MSTN, …

  • ‘array element ID’: e.g., 01, 02, …

  • ‘array element design type’: e.g., design, test

  • ‘instrument class key’: e.g., telescope, camera, structure

  • ‘db collection’: e.g., telescopes, sites, calibration_devices

utils.names.generate_file_name(file_type, suffix, site, telescope_model_name, zenith_angle, azimuth_angle=None, off_axis_angle=None, source_distance=None, mirror_number=None, label=None, extra_label=None)[source]#

Generate a file name for output, config, or plotting.

Used e.g., to generate camera_efficiency and ray_tracing output files.

Parameters:
file_type: str

Type of file (e.g., config, output, plot)

suffix: str

File suffix

site: str

South or North.

telescope_model_name: str

LSTN-01, MSTS-01, …

zenith_angle: float

Zenith angle (deg).

azimuth_angle: float

Azimuth angle (deg).

off_axis_angle: float

Off-axis angle (deg).

source_distance: float

Source distance (km).

mirror_number: int

Mirror number.

label: str

Instance label.

extra_label: str

Extra label.

Returns:
str

File name.

utils.names.get_array_element_type_from_name(array_element_name)[source]#

Get array element type from array element name (e.g “MSTN” from “MSTN-01”).

For sites, return site name.

Parameters:
array_element_name: str

Array element name

Returns:
str

Array element type.

utils.names.get_site_from_array_element_name(array_element_name)[source]#

Get site name from array element name (e.g., “South” from “MSTS-01”).

Parameters:
array_element_name: str

Array element name.

Returns:
str, list

Site name(s).

utils.names.sanitize_name(name)[source]#

Sanitize name to be a valid Python identifier.

  • Replaces spaces with underscores

  • Converts to lowercase

  • Removes characters that are not alphanumerics or underscores

  • If the name starts with a number, prepend an underscore

Parameters:
name: str

name to be sanitized.

Returns:
str:

Sanitized name.

Raises:
ValueError:

if the string name can not be sanitized.

utils.names.simtel_config_file_name(site, model_version, array_name=None, telescope_model_name=None, label=None, extra_label=None)[source]#

sim_telarray config file name for a telescope.

Parameters:
site: str

South or North.

telescope_model_name: str

LST-1, MST-FlashCam, …

model_version: str

Version of the model.

label: str

Instance label.

extra_label: str

Extra label in case of multiple telescope config files.

Returns:
str

File name.

utils.names.simtel_single_mirror_list_file_name(site, telescope_model_name, model_version, mirror_number, label)[source]#

sim_telarray mirror list file with a single mirror.

Parameters:
site: str

South or North.

telescope_model_name: str

North-LST-1, South-MST-FlashCam, …

model_version: str

Version of the model.

mirror_number: int

Mirror number.

label: str

Instance label.

Returns:
str

File name.

utils.names.validate_array_element_id_name(array_element_id, array_element_type=None)[source]#

Validate array element ID.

Allowed IDs are - design types (for design array elements or testing) - array element ID (e.g., 1, 5, 15) - test (for testing)

Parameters:
name: str or int

Array element ID name.

array_element_type: str

Array element type (e.g., LSTN, MSTN).

Returns:
str

Validated array element ID (added leading zeros, e.g., 1 is converted to 01).

Raises:
ValueError

If name is not valid.

utils.names.validate_array_element_name(array_element_name)[source]#

Validate array element name (e.g., MSTx-NectarCam, MSTN-01).

Forgiving validation, is it allows also to give a site name (e.g., OBS-North).

Parameters:
array_element_name: str

Array element name.

Returns:
str

Validated name.

utils.names.validate_site_name(site_name)[source]#

Validate site name.

Parameters:
site_name: str

Site name.

Returns:
str

Validated name.

value_conversion#

Value and quantity conversion.

utils.value_conversion.extract_type_of_value(value) → str[source]#

Extract the string representation of the the type of a value.

For example, for a string, it returns ‘str’ rather than ‘<class ‘str’>’. Take into account also the case where the value is a numpy type.

utils.value_conversion.get_value_as_quantity(value, unit)[source]#

Get a value as a Quantity with a given unit. If value is a Quantity, convert to the given unit.

Parameters:
value:

value to get a unit. It can be a float, int, or a Quantity (convertible to ‘unit’).

unit: astropy.units.Unit

Unit to apply to ‘quantity’.

Returns:
astropy.units.Quantity

Quantity of value ‘quantity’ and unit ‘unit’.

Raises:
u.UnitConversionError

If the value cannot be converted to the given unit.

utils.value_conversion.get_value_unit_type(value, unit_str=None)[source]#

Get the value, unit and type of a value.

The value is stripped of its unit and the unit is returned in its string form (i.e., to_string()). The type is returned as a string representation of the type. For example, for a string, it returns ‘str’ rather than ‘<class ‘str’>’. An additional unit string can be given and the return value is converted to this units.

Note that Quantities are always floats, even if the original value is represented as an int.

Parameters:
value: str, int, float, bool, u.Quantity

Value to be parsed.

unit_str: str

Unit to be used for the value.

Returns:
type of value, str, str

Value, unit in string representation (to_string())), and string representation of the type of the value.

utils.value_conversion.split_value_and_unit(value, is_integer=False)[source]#

Split a value into its value and unit.

Takes into account the case where the value is a Quantity, a number, or a simtools-type string encoding a list of values and units.

Parameters:
value: str, int, float, bool, u.Quantity

Value to be parsed.

is_integer: bool

Flag to indicate if the value is an integer.

Returns:
value, str

Value and units as (value, unit), or lists of values and unites

constants#

Project wide constants.