Configuration#

Reference documentation for the configuration of simtools applications.

configurator#

Application configuration.

class simtools.configuration.configurator.Configurator(label=None, description=None, usage=None, use_dependency_defaults=True)[source]#

Application configuration.

Allow to set configuration parameters by

command line arguments
configuration file
environmental variables

Assigns unique ACTIVITY_ID to this configuration (uuid).

Configuration parameter names are converted always to lower case.

Parameters:

label: str: Class label.
description: str: Text displayed as description.
usage: str: Application usage description.

configure(initialize_output=False)[source]#

Initialize configuration from an already populated parser.

Parameters:

initialize_outputbool: Generate a default output filename when none is configured.

Returns:

dict: Parsed application configuration.

commandline_parser#

Command-line parser for explicitly defined applications.

class simtools.configuration.commandline_parser.CommandLineParser(*args, **kwargs)[source]#

Argument parser that registers explicit argument definitions.

add_argument_definitions(arguments)[source]#

Register a sequence of explicit argument definitions.

Parameters:

argumentsiterable of ArgumentDefinition: Arguments to register in declaration order.

declared_defaults()[source]#: Return declared argument defaults and argparse action defaults.

parse_explicit_args(args)[source]#

Return only the options given on the command line, converted by their types.

Defaults are not filled in and required arguments are not checked, so that values from other sources can be merged first.

Parameters:

argslist of str: Command-line arguments.

Returns:

dict: Explicitly given options.

arguments#

Authoritative command-line argument definitions for simtools applications.

class simtools.configuration.arguments.ArgumentDefinition(name, *, group=None, exclusive_group=None, exclusive_group_required=False, preserve_by_version=False, aliases=(), **kwargs)[source]#

Definition of one command-line argument.

without_requiredness()[source]#: Return a copy whose required constraints can be validated after parsing.

simtools.configuration.arguments.corsika_configuration_arguments(*, primary_required=True)[source]#: Return CORSIKA arguments with application-specific primary requiredness.

simtools.configuration.arguments.layout_selection_arguments(*, required=True, include_file=False, include_parameter_file=False, include_plot_all=False)[source]#: Return the standard mutually exclusive array-layout selections.

argument_helpers#

Command-line argument conversion and validation helpers.

class simtools.configuration.argument_helpers.BuildInfoAction(option_strings, dest='==SUPPRESS==', default='==SUPPRESS==', **kwargs)[source]#: Custom argparse action to display build information.

class simtools.configuration.argument_helpers.OneOrManyAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)[source]#: Store one value as scalar and multiple values as list.

class simtools.configuration.argument_helpers.QuantityPairAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)[source]#: Parse either one quantity-pair string or two quantity values.

simtools.configuration.argument_helpers.azimuth_angle(angle)[source]#

Validate and return an azimuth angle in [0, 360] degrees.

Parameters:

anglefloat or str or astropy.Quantity: Azimuth angle to validate. Can be numerical value or cardinal direction (north, south, east, west).

Returns:

astropy.Quantity: Azimuth angle in degrees.

Raises:

argparse.ArgumentTypeError: If angle is outside [0, 360] interval or invalid string.

simtools.configuration.argument_helpers.bounded_int(min_value, max_value)[source]#

Create an argument parser type to check that an integer is within a given interval.

Parameters:

min_valueint: Minimum allowed value (inclusive).
max_valueint: Maximum allowed value (inclusive).

Returns:

function: Parser function that validates integers in the given range.

Raises:

ValueError: If integer is outside the specified interval.

simtools.configuration.argument_helpers.coerce(definition, value, source)[source]#: Convert and validate a value supplied outside the command line.

simtools.configuration.argument_helpers.configuration_from_environment(parser, env_file)[source]#: Read environment values registered by a parser, preferring process values.

simtools.configuration.argument_helpers.configuration_from_file(config_file, parser)[source]#: Read a YAML configuration and resolve version-specific values.

simtools.configuration.argument_helpers.efficiency_interval(value)[source]#

Validate that value is an efficiency in the interval [0, 1].

Parameters:

valuefloat: Efficiency value to validate.

Returns:

float: Validated efficiency value.

Raises:

argparse.ArgumentTypeError: If value is outside [0, 1] interval.

simtools.configuration.argument_helpers.instrument(value)[source]#

Validate and return an instrument name.

Parameters:

valuestr: Instrument name to validate.

Returns:

str: Validated instrument name.

Raises:

ValueError: If instrument name is invalid.

simtools.configuration.argument_helpers.nonnegative_quantity(target_unit)[source]#

Return a parser that parses a quantity and enforces >= 0.

Parameters:

target_unitstr or astropy.units.Unit: Target unit for conversion.

Returns:

function: Parser function that returns nonnegative quantities.

Raises:

argparse.ArgumentTypeError: If quantity is negative.

simtools.configuration.argument_helpers.normalize_argument_aliases(config, parser)[source]#: Map aliases from external configuration to canonical argument names.

simtools.configuration.argument_helpers.parse_integer_and_quantity(input_string)[source]#

Parse a string representing an integer and a quantity with units.

Parameters:

input_stringstr: String containing an integer and a quantity (e.g., “10 20.5 m”).

Returns:

tuple: Tuple of (integer, astropy.Quantity).

Raises:

ValueError: If string does not contain valid integer and quantity.

simtools.configuration.argument_helpers.parse_quantity_pair(string)[source]#

Parse a string representing a pair of astropy quantities.

Parameters:

stringstr: String containing two quantities (e.g., “10 m 20 cm”).

Returns:

tuple: Tuple of two astropy.Quantity objects.

Raises:

ValueError: If string does not contain exactly two quantities.

simtools.configuration.argument_helpers.positive_quantity(target_unit)[source]#

Return a parser that parses a quantity and enforces > 0.

Parameters:

target_unitstr or astropy.units.Unit: Target unit for conversion.

Returns:

function: Parser function that returns positive quantities.

Raises:

argparse.ArgumentTypeError: If quantity is not positive.

simtools.configuration.argument_helpers.quantity(target_unit)[source]#

Build an argument parser type for quantities convertible to a target unit.

Parameters:

target_unitstr or astropy.units.Unit: Target unit for conversion.

Returns:

function: Parser function that converts input to quantities in target unit.

Raises:

argparse.ArgumentTypeError: If value cannot be converted to target unit.

simtools.configuration.argument_helpers.scientific_int(value)[source]#

Convert string (including scientific notation) to integer.

Parameters:

valuestr: String value to convert.

Returns:

int: Integer value.

Raises:

argparse.ArgumentTypeError: If value cannot be converted to integer.

simtools.configuration.argument_helpers.site(value)[source]#

Validate and return a site name.

Parameters:

valuestr: Site name to validate.

Returns:

str: Validated site name.

Raises:

ValueError: If site name is invalid.

simtools.configuration.argument_helpers.string_or_dict(value)[source]#

Parse argument as plain string or dictionary literal.

Parameters:

valuestr: Value to parse.

Returns:

str or dict: Parsed value as string or dictionary.

simtools.configuration.argument_helpers.string_or_list(value)[source]#

Parse a bracketed list literal, or preserve the original value.

Parameters:

valuestr or list: Command-line value to parse.

Returns:

list or str: Parsed list when value contains a valid list literal; otherwise the input value.

simtools.configuration.argument_helpers.telescope(value)[source]#

Validate and return telescope name(s).

Parameters:

valuestr or list: Telescope name or list of telescope names to validate.

Returns:

str or list: Validated telescope name(s).

Raises:

ValueError: If telescope name(s) are invalid.

simtools.configuration.argument_helpers.validate_site_telescope_consistency(config, parser)[source]#: Reject telescope selections that belong to a different configured site.

simtools.configuration.argument_helpers.zenith_angle(angle)[source]#

Validate and return a zenith angle in [0, 180] degrees.

Parameters:

anglefloat or str or astropy.Quantity: Zenith angle to validate.

Returns:

astropy.Quantity: Zenith angle in degrees.

Raises:

argparse.ArgumentTypeError: If angle is outside [0, 180] interval.

show_options#

Shared option-discovery helpers for selected command-line arguments.

class simtools.configuration.show_options.ShowOptionsResult(option_name, help_text=None, environment=<factory>, values=(), grouped_values=<factory>, notes=())[source]#: Normalized output for --show_options.

simtools.configuration.show_options.format_show_options_result(result)[source]#: Format one ShowOptionsResult.

simtools.configuration.show_options.handle_show_options(args_dict, parser, context=None)[source]#: Print available values for a supported option and exit.

simtools.configuration.show_options.resolve_show_options(args_dict, parser=None, context=None)[source]#: Resolve --show_options using a custom provider or parser metadata.

defaults#

Default values for CLI and settings configuration.