beamme.four_c.function_utility

  1# The MIT License (MIT)
  2#
  3# Copyright (c) 2018-2026 BeamMe Authors
  4#
  5# Permission is hereby granted, free of charge, to any person obtaining a copy
  6# of this software and associated documentation files (the "Software"), to deal
  7# in the Software without restriction, including without limitation the rights
  8# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9# copies of the Software, and to permit persons to whom the Software is
 10# furnished to do so, subject to the following conditions:
 11#
 12# The above copyright notice and this permission notice shall be included in
 13# all copies or substantial portions of the Software.
 14#
 15# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21# THE SOFTWARE.
 22"""This module implements utility functions to create 4C space time function."""
 23
 24import numpy as _np
 25
 26from beamme.core.function import Function as _Function
 27
 28
 29def create_linear_interpolation_dict(
 30    times: list[float], values: list[float], *, variable_name="var", variable_index=0
 31):
 32    """Create a string that describes a variable that is linear interpolated over time.
 33
 34    Args
 35        times, values:
 36            Time and values that will be interpolated with piecewise linear functions
 37        variable_name:
 38            Name of the created variable
 39        variable_index:
 40            Index of this created variable
 41    """
 42    if not len(times) == len(values):
 43        raise ValueError(
 44            f"The dimensions of time ({len(times)}) and values ({len(values)}) do not match"
 45        )
 46
 47    times_appended = _np.array(times)
 48    values_appended = _np.array(values)
 49    t_max = _np.max(times_appended)
 50    times_appended = _np.insert(times_appended, 0, -1000.0, axis=0)
 51    times_appended = _np.append(times_appended, [t_max + 1000.0])
 52    values_appended = _np.insert(values_appended, 0, values[0], axis=0)
 53    values_appended = _np.append(values_appended, values_appended[-1])
 54    return {
 55        "VARIABLE": variable_index,
 56        "NAME": variable_name,
 57        "TYPE": "linearinterpolation",
 58        "NUMPOINTS": len(times_appended),
 59        "TIMES": times_appended.tolist(),
 60        "VALUES": values_appended.tolist(),
 61    }
 62
 63
 64def create_linear_interpolation_function(
 65    times: list[float],
 66    values: list[float],
 67    *,
 68    function_type="SYMBOLIC_FUNCTION_OF_SPACE_TIME",
 69):
 70    """Create a function that describes a linear interpolation between the given time
 71    points and values. Before and after it will be constant.
 72
 73    Args
 74    ----
 75        times, values:
 76            Time and values that will be interpolated with piecewise linear functions
 77    """
 78    function_dict = create_linear_interpolation_dict(times, values, variable_name="var")
 79    return _Function([{function_type: "var"}, function_dict])
 80
 81
 82def ensure_length_of_function_array(function_array: list, length: int = 3):
 83    """Performs size check of a function array and appends the function array to the
 84    given length, if a list with only one item is provided.
 85
 86    Args:
 87        function_array: list with functions
 88        length: expected length of function array
 89
 90    Returns:
 91        function_array: list with functions with provided length
 92    """
 93    # extend items of function automatically if it is only provided once
 94    if len(function_array) == 1:
 95        function_array = function_array * length
 96
 97    if len(function_array) != length:
 98        raise ValueError(
 99            f"The function array must have length {length} not {len(function_array)}."
100        )
101    return function_array