Utilities#

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

constants#

Project wide constants.

constants.get_configured_test_resources_root()[source]#: Return the test-resource root configured for an application, if any.

constants.get_test_resources_root()[source]#: Return the test-resource root configured by the test harness.

general#

General functions useful across different parts of the code.

utils.general.cleanup_intermediate_files(output_dir, patterns=(), *, files=(), directories=(), exclude=())[source]#

Remove selected intermediate files and then selected empty directories.

Parameters:

output_dirstr or pathlib.Path: Directory in which to match glob patterns.
patternsiterable of str, optional: File patterns relative to output_dir. No patterns are selected by default.
filesiterable of pathlib.Path, optional: Explicit file paths to remove, independent of output_dir.
directoriesiterable of pathlib.Path, optional: Explicit directories to remove only when empty, deepest first.
excludeiterable of pathlib.Path, optional: Paths to preserve even when selected by a pattern or explicit list.

Returns:

int: Number of files removed. Missing files are ignored.

utils.general.extract_subdirectories_from_path(path, anchor='input')[source]#

Extract subdirectories in a path after an anchor directory.

Parameters:

pathstr or Path: Path containing an anchor directory and a filename.
anchorstr: Directory name used as extraction anchor.

Returns:

str: Subdirectory path between anchor and file name, joined with ‘/’.

Raises:

ValueError: If anchor is not present or no subdirectories are found after the anchor.

utils.general.extract_uuid7_from_path(path)[source]#

Extract UUID7 from path components if present.

Parameters:

pathstr or Path: Path potentially containing a UUID7 component.

Returns:

str or None: UUID7 string if found, otherwise None.

utils.general.find_executable_in_dir(name, directory)[source]#

Find an executable in the given directory.

Parameters:

name: str: Name of the executable to find.
directory: str or Path: Directory to search for the executable.

utils.general.find_file(name, loc)[source]#

Search for files inside of given directories, recursively, and return its full path.

Parameters:

name: str: File name to be searched for.
loc: Path or list of Path: Location of where to search for the file.

Returns:

Path: Full path of the file to be found if existing. Otherwise, None.

Raises:

FileNotFoundError: If the desired file is not found.

utils.general.get_uuid()[source]#

Generate a UUID (7) string.

Returns:

str: A UUID string.

utils.general.is_url(url)[source]#

Check if a string is a valid URL.

Parameters:

url: str: String to be checked.

Returns:

bool: True if url is a valid URL.

utils.general.load_environment_variables(env_file='.env', env_list=None)[source]#

Load environment variables (from a .env file or directly from the environment).

Allow to read a specific list of variables or all variables from the .env file.

Parameters:

env_file: str: Path to the .env file.
env_list: list, optional: List of environment variables to be read. If None, all variables are read.

Returns:

dict: Dictionary mapping environment variable names (lowercase, without the SIMTOOLS_ prefix) to their cleaned string values.

utils.general.now_date_time_in_isoformat()[source]#: Return date and time in isoformat and second accuracy.

utils.general.resolve_file_patterns(file_names)[source]#

Return a list of files names from string, list, or wildcard pattern.

Parameters:

file_names: str, list: File names to be searched for (wildcards allowed).

Returns:

list: List of file names found.

geometry#

telescope_fiducial_sphere_radius calculates a conservative CORSIKA sphere from cylindrical bounds on optical elements. Include every relevant element and its full surface sag and panel corners. Coordinates are relative to the mirror backplane; mirror_offset and both axes_offsets use sim_telarray conventions. The default pointing range is zenith angles from 0 to 90 degrees. Any extra clearance must be specified explicitly.

For the MST reference enclosure:

import astropy.units as u
from simtools.utils.geometry import telescope_fiducial_sphere_radius

radius = telescope_fiducial_sphere_radius(
    radial_extent=[6.90] * u.m,
    axial_extent=[[0, 1.28]] * u.m,
    axes_offsets=[1.60, 0] * u.m,
    mirror_offset=-1.775 * u.m,
)
# radius is approximately 9.15 m; additional elements require their own bounds.

A collection of functions related to geometrical transformations.

utils.geometry.calculate_circular_mean(angles)[source]#

Calculate circular mean of angles in radians.

Parameters:

angles: numpy.array: Array of angles in radians.

Returns:

float: Circular mean of the angles.

utils.geometry.fiducial_radius_from_shape(width, shape)[source]#

Calculate minimum radius including different geometrical shapes.

Assumes definition of shapes as in ‘camera_body_shape’ model parameter:

circle: shape = 0, width is diameter
hexagon: shape = 1 or 3, width is flat-to-flat distance
square: shape = 2, width is side length

Parameters:

widthfloat: Characteristic width
shapeint: Geometrical shape parameter

Returns:

float: Minimum fiducial radius

utils.geometry.geographic_to_corsika_azimuth(az_deg)[source]#

Convert geographic arrival azimuth to CORSIKA propagation azimuth.

The input is an astronomical/geographic azimuth: the direction from which the primary arrives, measured clockwise from geographic North toward East.

CORSIKA phi describes the direction toward which the primary propagates and increases from North toward West. The conversion therefore consists of:

Negating the angle because the two azimuth conventions increase in opposite directions.
Adding 180 degrees to convert an arrival direction into the opposite propagation direction.

No geomagnetic-field alignment correction is applied here.

Parameters:

az_degfloat: Geographic arrival azimuth in degrees, measured clockwise from geographic North toward East.

Returns:

float: CORSIKA propagation azimuth in degrees, before geomagnetic-field alignment correction.

utils.geometry.ground_direction_to_telescope_frame(direction, theta_deg, phi_deg)[source]#: Transform a direction from the ground frame into the telescope frame (see above).

utils.geometry.ground_to_telescope_frame(point, theta_deg, phi_deg, axes_offsets=())[source]#

Transform a point relative to the telescope position into the telescope frame.

The ground frame is the array frame (x north, y west, z up); the telescope frame has +z along the optical axis.

Parameters:

point: array_like: Point relative to the telescope position (ground frame).
theta_deg, phi_deg: float: Telescope pointing: zenith angle and azimuth (array frame) [deg].
axes_offsets: sequence of float: Offsets azimuth axis - altitude axis and altitude axis - optical axis (same unit as point); missing values are zero.

Returns:

numpy.ndarray: Point in the telescope frame.

utils.geometry.project_ground_to_corsika_shower_coordinates(x_ground, y_ground, z_ground, azimuth_from_north_east, altitude)[source]#

Transform ground to shower coordinates following the CORSIKA/sim_telarray convention.

This function applies the same horizontal coordinate transformation used internally by sim_telarray for shower-oriented coordinates.

Input ground coordinates follow the CORSIKA/sim_telarray ground system:

x_ground : points North
y_ground : points West
z_ground : points Up

The input azimuth is assumed to follow the standard astronomical convention:

0 rad = North
pi/2 = East

Internally, the azimuth is converted to the CORSIKA ‘phi’ convention used in ‘iact.c’:

phi = 0 : shower propagates toward North
phi = pi/2 : shower propagates toward West

The transformation corresponds to the inverse of the projection applied in sim_telarray when converting shower coordinates into ground coordinates.

Parameters:

x_ground: numpy.array: Ground x coordinate.
y_ground: numpy.array: Ground y coordinate.
z_ground: numpy.array: Ground z coordinate.
azimuth_from_north_east: numpy.array: Azimuth angle of the shower (in radians).
altitude: numpy.array: Altitude angle of the shower (in radians).

Returns:

tuple: Transformed shower coordinates (x’, y’, z’).

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

Rotate the x and y coordinates of the telescopes.

The two rotations are:

rotation_around_z_axis gives the rotation on the observation plane (x, y)
rotation_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_around_z_axis: astropy.units.rad: Angle to rotate the array in the observation plane (around z axis) in radians.
rotation_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.

utils.geometry.solid_angle(angle_max, angle_min=<Quantity 0. rad>)[source]#

Calculate the solid angle subtended by a given range of angles.

Parameters:

angle_max: astropy.units.Quantity: The maximum angle for which to calculate the solid angle.
angle_min: astropy.units.Quantity: The minimum angle for which to calculate the solid angle (default is 0 rad).

Returns:

astropy.units.Quantity: The solid angle subtended by the given range of angles (in steradians).

utils.geometry.telescope_fiducial_sphere_radius(radial_extent, axial_extent, axes_offsets, mirror_offset=<Quantity 0. m>, zenith_range=<Quantity [ 0., 90.] deg>, margin=<Quantity 0. m>)[source]#

Enclose optical elements for a continuous range of telescope pointings.

Each element is bounded by a cylinder about the optical axis. Use bounds containing the entire surface, including panel corners and surface sag, for every relevant primary, secondary and camera element. The result is conservative for these enclosing cylinders, rather than a minimum sphere for the individual optical surfaces. Azimuth rotations preserve distance from the CORSIKA sphere center.

Parameters:

radial_extentastropy.units.Quantity: One maximum radial distance from the optical axis per element.
axial_extentastropy.units.Quantity: Array of shape (number of elements, 2) giving each element’s minimum and maximum axial coordinate relative to the mirror backplane.
axes_offsetsastropy.units.Quantity: The two sim_telarray offsets: azimuth-to-altitude axis, followed by altitude-to-optical axis. Positive offsets follow axes_offsets.
mirror_offsetastropy.units.Quantity, optional: sim_telarray mirror-backplane offset from the altitude axis.
zenith_rangeastropy.units.Quantity, optional: Minimum and maximum zenith angle, within [0, 180] degrees.
marginastropy.units.Quantity, optional: Nonnegative extra radial clearance. No clearance is added by default.

Returns:

astropy.units.Quantity: Required radius about the CORSIKA telescope position, in meters.

Raises:

ValueError: If bounds are empty, malformed, non-finite or outside their allowed ranges.

Notes

The offsets follow tel_newdir and transform_off in sim_telarray. The calculation checks the endpoints and analytic stationary points of the distance over zenith angle; it does not sample a pointing grid.

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
‘model repository collection’: e.g., telescopes, sites, calibration_devices

utils.names.array_element_common_identifiers()[source]#

Get array element IDs from CTAO common identifier.

Returns:

dict, dict: Dictionary mapping array element names to their IDs and vice versa.

utils.names.array_element_design_types(array_element_type)[source]#

Get array element design type (e.g., ‘design’ or ‘flashcam’).

Default values are [‘design’, ‘test’].

Parameters:

array_element_type: Array element type

Returns:

list: Array element design types.

utils.names.array_elements()[source]#

Get array elements and their properties.

Returns:

dict: Array elements.

utils.names.file_name_with_version(file_name, suffix)[source]#

Return a file name including a semantic version with the correct suffix.

Replaces ‘Path.suffix()’, which removes trailing numbers (and therefore version numbers).

Parameters:

file_name: str: File name.
suffix: str: File suffix.

Returns:

Path: File name with version number.

utils.names.generate_array_element_name_from_type_site_id(array_element_type, site, array_element_id)[source]#

Generate a new array element name from array element type, site, and array element ID.

Parameters:

array_element_type: str: Array element type.
site: str: Site name.
array_element_id: str: Array element ID.

Returns:

str: Array element name.

utils.names.generate_file_name(file_type, suffix, site, telescope_model_name, zenith_angle, azimuth_angle=None, off_axis_angle=None, off_axis_x=None, off_axis_y=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). Use off_axis_x and off_axis_y for (x, y) offsets.
off_axis_x: float: X component of off-axis offset (deg).
off_axis_y: float: Y component of off-axis offset (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_id_from_name(array_element_name)[source]#

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

Parameters:

array_element_name: str: Array element name

Returns:

str: Array element ID.

utils.names.get_array_element_name_from_common_identifier(common_identifier)[source]#

Get array element name from common identifier as used by CTAO.

Common identifiers are numerical IDs used by the CTAO ACADA and DPPS systems.

Parameters:

common_identifier: int: Common identifier.

Returns:

str: Array element 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_collection_name_from_array_element_name(array_element_name, array_elements_only=True)[source]#

Get collection name (e.g., telescopes, calibration_devices) of an array element from its name.

Parameters:

array_element_name: str: Array element name (e.g. LSTN-01)
array_elements_only: bool: If True, only array elements are considered (e.g. “OBS-North” will raise a ValueError).

Returns:

str: Collection name .

Raises:

ValueError: If name is not a valid array element name.

utils.names.get_common_identifier_from_array_element_name(array_element_name, default_return=None)[source]#

Get numerical common identifier from array element name as used by CTAO.

Common identifiers are numerical IDs used by the CTAO ACADA and DPPS systems.

Parameters:

array_element_name: str: Array element name (e.g. LSTN-01)

Returns:

int: Common identifier.

utils.names.get_list_of_array_element_types(array_element_class='telescopes', site=None, observatory='CTAO')[source]#

Get list of array element types (e.g., [“LSTN”, “MSTN”] for the Northern site).

Parameters:

array_element_class: str: Array element class
site: str: Site name (e.g., South or North).

Returns:

list: List of array element types.

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.is_design_type(array_element_name)[source]#

Check if array element is a design type (e.g., “MSTS-FlashCam” or “LSTN-design”).

Parameters:

array_element_name: str: Array element name.

Returns:

bool: True if array element is a design type.

utils.names.is_two_mirror_telescope(telescope_model_name)[source]#: Return True for two-mirror telescopes (SST and SCT).

utils.names.matches_array_element_name_or_design_type(element_name, reference_element_name)[source]#

Check whether an array element name matches a reference exactly or by design type equivalence.

Parameters:

element_name: str: Candidate element name to validate and compare (e.g., “MSTN-01” or “MSTx-FlashCam”).
reference_element_name: str: Reference array element name used for comparison (e.g., “MSTN-01” or “MSTN-FlashCam”).

Returns:

bool: True if both names are identical, or if they belong to the same design type.

utils.names.normalize_array_element_identifier(array_element_identifier)[source]#

Normalize an array element identifier to an array element name when possible.

Parameters:

array_element_identifierstr or int: Array element identifier. Can be a CTAO common numerical identifier (used by ACADA/DPPS) or already an array element name.

Returns:

str: Normalized array element identifier.

utils.names.normalize_array_element_identifier_container(array_element_identifiers)[source]#

Normalize a container of array element identifiers.

Parameters:

array_element_identifiersstr or list or tuple or set or None: Array element identifiers, possibly encoded as a JSON list string (for example the serialized content of an ECSV subtype: json field).

Returns:

list: List of normalized array element identifiers.

utils.names.sim_telarray_config_file_name(site, array_name=None, telescope_model_name=None)[source]#

sim_telarray configuration file name for an array or a telescope.

Parameters:

site: str: South or North.
array_name: str: Array name (e.g., CTAO-North-4-LSTs-1-MSTs)
telescope_model_name: str: Telescope name (e.g., LSTN-01, MSTS-05)

Returns:

str: Configuration 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.site_names()[source]#

Get site names.

The list of sites is derived from the sites listed in array element definition file. Return a dictionary for compatibility with the validation ‘_validate_name’ routine.

Returns:

dict: Site names.

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_array_element_type(array_element_type)[source]#

Validate array element type (e.g., LSTN, MSTN).

Parameters:

array_element_type: str: Array element type.

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.

random numbers#

Random numbers utilities.

utils.random.instance_seeds(seed, instances, max_seed=2000000000)[source]#

Seeds of random instances derived from one seed.

Parameters:

seedint: Seed the instance seeds are derived from.
instancesint: Number of instances.
max_seedint: Upper limit for the derived seeds (exclusive).

Returns:

list of int: The seed itself for a single instance, otherwise instances derived seeds.

utils.random.seeds(n_seeds=1, min_seed=1, max_seed=2000000000, fixed_seed=None)[source]#

Generate independent random seeds.

Parameters:

n_seedsint: Number of seeds to generate.
min_seedint: Lower limit for the seed (inclusive).
max_seedint: Upper limit for the seed (exclusive).
fixed_seedint or None: If provided, use this fixed seed.

Returns:

int or list of int:: A single seed if n_seeds is 1, otherwise a list of seeds.

value_conversion#

Value and quantity conversion.

utils.value_conversion.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.value_conversion.convert_keys_in_dict_to_lowercase(data)[source]#

Recursively convert all dictionary keys to lowercase.

Parameters:

data: dict: Dictionary to be converted.

Returns:

dict: Dictionary with all keys converted to lowercase.

utils.value_conversion.convert_list_to_string(data, comma_separated=False, shorten_list=False, collapse_list=False)[source]#

Convert arrays to string (if required).

Parameters:

data: object: Object of data to convert (e.g., double or list)
comma_separated: bool: If True, returns elements as a comma-separated string (default is space-separated).
shorten_list: bool: If True and all elements in the list are identical, returns a summary string like “all: value”. This is useful to make the configuration files more readable.
collapse_list: bool: If True and all elements in the list are identical, returns a single value instead of the entire list.

Returns:

object or str:: Converted data as string (if required)

utils.value_conversion.convert_string_to_list(data_string, is_float=True, force_comma_separation=False)[source]#

Convert string (as used e.g. in sim_telarray) to list.

Allow coma or space separated strings.

Parameters:

data_string: object: String to be converted
is_float: bool: If True, convert to float, otherwise to int.
force_comma_separation: bool: If True, force comma separation.

Returns:

list, str: Converted data from string (if required). Return data_string if conversion fails.

utils.value_conversion.ensure_list(value)[source]#

Return input value as list.

Parameters:

value: any: Input value to be converted to a list.

Returns:

list: Converted value as list.

utils.value_conversion.ensure_string_lists(value)[source]#

Ensure the input value is returned as a list of strings.

Parameters:

valueany: Input value to convert to a list of strings.

Returns:

list or None: List of strings or None if the input is None.

utils.value_conversion.extract_type_of_value(value)[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:

ValueError: If the value cannot be converted to the given unit.

utils.value_conversion.get_value_in_unit(value, unit=None)[source]#

Return the numerical value of a Quantity in the requested unit.

Parameters:

value: astropy.units.Quantity or any: Value to be converted.
unit: astropy.units.Unit or str or None: Unit to convert the value to.

Returns:

float or any: Numerical value of the Quantity in the requested unit, or the original value if it is not a Quantity and no target unit is requested.

Raises:

TypeError: If unit is requested but value is neither a Quantity nor a numeric scalar.

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.is_dimensionless_unit(unit)[source]#

Return True if unit encodes a dimensionless quantity.

Parameters:

unit: str, object, or None: Unit string or Astropy unit object to be checked.

Returns:

bool True if the unit encodes a dimensionless quantity, False otherwise.

utils.value_conversion.normalize_dimensionless_unit(unit)[source]#

Normalize dimensionless unit markers to None.

Parameters:

unit: str, object, or None: Unit string or Astropy unit object to be normalized.

Returns:

str, object, or None: Normalized unit, where dimensionless units are converted to None.

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

Normalize a model parameter unit for use by model repository consumers.

Parameters:

valueobject: Model parameter value associated with the unit.
unitstr, list, numpy.ndarray, or None: Unit representation to normalize.

Returns:

str, list, or None: Normalized unit. Scalar units are canonicalized for scalar values and retained for list-valued parameters.

utils.value_conversion.parse_typed_sequence(value, cast=<class 'float'>)[source]#

Parse scalar or sequence input into a list of typed values.

Parameters:

valueany: Input value to parse. Supported forms are None, scalar values, list/tuple, or comma-separated strings.
castcallable, optional: Conversion callable applied to each parsed item. Defaults to float.

Returns:

list: List of converted values. Returns an empty list when value is None.

utils.value_conversion.remove_key_from_dict(data, key_to_remove)[source]#

Remove a specific key from a dictionary recursively.

Parameters:

data: dict: Dictionary to be processed.
key_to_remove: str: Key to be removed from the dictionary.

Returns:

dict: Dictionary with the specified key removed.

utils.value_conversion.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.value_conversion.replace_placeholders_recursively(data, replacements)[source]#

Replace placeholders recursively in strings nested in dicts/lists.

Parameters:

datadict, list, str, or object: Input structure to process.
replacementsdict: Mapping of placeholder strings to replacement strings.

Returns:

dict, list, str, or object: Processed copy with placeholders replaced in string values.

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

utils.value_conversion.validate_data_type(reference_dtype, value=None, dtype=None, allow_subtypes=True)[source]#

Validate data type of value or type object against a reference data type.

Allow to check for exact data type or allow subtypes (e.g. uint is accepted for int). Take into account ‘file’ type as used in the model parameter repository.

Parameters:

reference_dtype: str: Reference data type to be checked against.
value: any, optional: Value to be checked (if dtype is None).
dtype: type, optional: Type object to be checked (if value is None).
allow_subtypes: bool, optional: If True, allow subtypes to be accepted.

Returns:

bool:: True if the data type is valid.