# Tools functions#

rocketpy.tools.tuple_handler(value)[source]#

Transforms the input value into a tuple that represents a range. If the input is an input or float, the output is a tuple from zero to the input value. If the input is a tuple or list, the output is a tuple with the same range.

Parameters:

value (`int`, `float`, `tuple`, `list`) – Input value.

Returns:

Tuple that represents the inputted range.

Return type:

`tuple`

rocketpy.tools.bilinear_interpolation(x, y, x1, x2, y1, y2, z11, z12, z21, z22)[source]#

Bilinear interpolation. It considers the values of the four points around the point to be interpolated and returns the interpolated value. Made with a lot of help from GitHub Copilot.

Parameters:
• x (`float`) – x coordinate to which the value will be interpolated.

• y (`float`) – y coordinate to which the value will be interpolated.

• x1 (`float`) – x coordinate of the first point.

• x2 (`float`) – x coordinate of the second point.

• y1 (`float`) – y coordinate of the first point.

• y2 (`float`) – y coordinate of the second point.

• z11 (`float`) – Value at the first point.

• z12 (`float`) – Value at the second point.

• z21 (`float`) – Value at the third point.

• z22 (`float`) – Value at the fourth point.

Returns:

Interpolated value.

Return type:

`float`

Examples

```>>> from rocketpy.tools import bilinear_interpolation
>>> bilinear_interpolation(0.5, 0.5, 0, 1, 0, 1, 0, 1, 1, 0)
0.5
```
rocketpy.tools.find_two_closest_integers(number)[source]#

Find the two closest integer factors of a number.

Parameters:

number (`int`) –

Returns:

Two closest integer factors of the number.

Return type:

`tuple`

Examples

```>>> from rocketpy.tools import find_two_closest_integers
>>> find_two_closest_integers(10)
(2, 5)
>>> find_two_closest_integers(12)
(3, 4)
>>> find_two_closest_integers(13)
(1, 13)
>>> find_two_closest_integers(150)
(10, 15)
```
rocketpy.tools.time_num_to_date_string(time_num, units, timezone, calendar='gregorian')[source]#

Convert time number (usually hours before a certain date) into two strings: one for the date (example: 2022.04.31) and one for the hour (example: 14). See cftime.num2date for details on units and calendar. Automatically converts time number from UTC to local timezone based on lat, lon coordinates. This function was created originally for the EnvironmentAnalysis class.

Parameters:
• time_num (`float`) – Time number to be converted.

• units (`str`) – Units of the time number. See cftime.num2date for details.

• timezone (`pytz.timezone`) – Timezone to which the time number will be converted. See pytz.timezone for details.

• calendar (`str`, optional) – Calendar to be used. See cftime.num2date for details.

Returns:

• date_string (`str`) – Date string.

• hour_string (`str`) – Hour string.

• date_time (`datetime.datetime`) – Datetime object.

Compute height above sea level from geopotential.

Parameters:
• geopotential (`float`) – Geopotential in m^2/s^2. It is the geopotential value at a given pressure level, to be converted to height above sea level.

• radius (`float`, optional) – Earth radius in m. Default is 63781370 m.

• g (`float`, optional) – Gravity acceleration in m/s^2. Default is 9.80665 m/s^2.

Returns:

geopotential_to_height_asl – Height above sea level in m

Return type:

`float`

Examples

```>>> from rocketpy.tools import geopotential_to_height_asl
>>> geopotential_to_height_asl(0)
0.0
>>> geopotential_to_height_asl(100000)
10198.792680243916
>>> geopotential_to_height_asl(200000)
20400.84750449947
```

Compute height above ground level from geopotential and elevation.

Parameters:
• geopotential (`float`) – Geopotential in m^2/s^2. It is the geopotential value at a given pressure level, to be converted to height above ground level.

• elevation (`float`) – Surface elevation in m

• radius (`float`, optional) – Earth radius in m. Default is 63781370 m.

• g (`float`, optional) – Gravity acceleration in m/s^2. Default is 9.80665 m/s^2.

Returns:

height_above_ground_level – Height above ground level in m

Return type:

`float`

Examples

```>>> from rocketpy.tools import geopotential_to_height_agl
>>> geopotential_to_height_agl(0, 0)
0.0
>>> geopotential_to_height_agl(100000, 0)
10198.792680243916
>>> geopotential_to_height_agl(100000, 1000)
9198.792680243916
```
rocketpy.tools.find_closest(ordered_sequence, value)[source]#

Find the index of the closest value to a given value within an ordered sequence.

Parameters:
• ordered_sequence (`list`) – A sequence of values that is ordered from smallest to largest.

• value (`float`) – The value to which you want to find the closest value.

Returns:

index – The index of the closest value to the given value within the ordered sequence. If the given value is lower than the first value in the sequence, then 0 is returned. If the given value is greater than the last value in the sequence, then the index of the last value in the sequence is returned.

Return type:

`int`

Examples

```>>> from rocketpy.tools import find_closest
>>> find_closest([1, 2, 3, 4, 5], 0)
0
>>> find_closest([1, 2, 3, 4, 5], 1.5)
0
>>> find_closest([1, 2, 3, 4, 5], 2.0)
1
>>> find_closest([1, 2, 3, 4, 5], 2.8)
2
>>> find_closest([1, 2, 3, 4, 5], 4.9)
4
>>> find_closest([1, 2, 3, 4, 5], 5.5)
4
>>> find_closest([], 10)
0
```
rocketpy.tools.import_optional_dependency(name)[source]#

Import an optional dependency. If the dependency is not installed, an ImportError is raised. This function is based on the implementation found in pandas repository: github.com/pandas-dev/pandas/blob/main/pandas/compat/_optional.py

Parameters:
• name (`str`) – The name of the module to import. Can be used to import submodules too. The name will be used as an argument to importlib.import_module method.

• Examples

• ---------

• import_optional_dependency (>>> from rocketpy.tools import) –

• import_optional_dependency("matplotlib") (>>> matplotlib =) –

• matplotlib.__name__ (>>>) –

• 'matplotlib'

• import_optional_dependency("matplotlib.pyplot") (>>> plt =) –

• plt.__name__ (>>>) –

• 'matplotlib.pyplot'

rocketpy.tools.check_requirement_version(module_name, version)[source]#

This function tests if a module is installed and if the version is correct. If the module is not installed, an ImportError is raised. If the version is not correct, an error is raised.

Parameters:
• module_name (`str`) – The name of the module to be tested.

• version (`str`) – The version of the module that is required. The string must start with one of the following operators: “>”, “<”, “>=”, “<=”, “==”, “!=”.

• Example

• --------

• check_requirement_version (>>> from rocketpy.tools import) –

• check_requirement_version("numpy" (>>>) –

• ">=1.0.0")

• True

• check_requirement_version("matplotlib" (>>>) –

• ">=3.0")

• True