beamme.four_c.function_utility

  1# The MIT License (MIT)
  2#
  3# Copyright (c) 2018-2025 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
 23function."""
 24
 25from typing import List as _List
 26
 27import numpy as _np
 28
 29from beamme.core.function import Function as _Function
 30
 31
 32def create_linear_interpolation_dict(
 33    times: _List[float], values: _List[float], *, variable_name="var", variable_index=0
 34):
 35    """Create a string that describes a variable that is linear interpolated
 36    over time.
 37
 38    Args
 39        times, values:
 40            Time and values that will be interpolated with piecewise linear functions
 41        variable_name:
 42            Name of the created variable
 43        variable_index:
 44            Index of this created variable
 45    """
 46
 47    if not len(times) == len(values):
 48        raise ValueError(
 49            f"The dimensions of time ({len(times)}) and values ({len(values)}) do not match"
 50        )
 51
 52    times_appended = _np.array(times)
 53    values_appended = _np.array(values)
 54    t_max = _np.max(times_appended)
 55    times_appended = _np.insert(times_appended, 0, -1000.0, axis=0)
 56    times_appended = _np.append(times_appended, [t_max + 1000.0])
 57    values_appended = _np.insert(values_appended, 0, values[0], axis=0)
 58    values_appended = _np.append(values_appended, values_appended[-1])
 59    return {
 60        "VARIABLE": variable_index,
 61        "NAME": variable_name,
 62        "TYPE": "linearinterpolation",
 63        "NUMPOINTS": len(times_appended),
 64        "TIMES": times_appended.tolist(),
 65        "VALUES": values_appended.tolist(),
 66    }
 67
 68
 69def create_linear_interpolation_function(
 70    times: _List[float],
 71    values: _List[float],
 72    *,
 73    function_type="SYMBOLIC_FUNCTION_OF_SPACE_TIME",
 74):
 75    """Create a function that describes a linear interpolation between the
 76    given time points and values. Before and after it will be constant.
 77
 78    Args
 79    ----
 80        times, values:
 81            Time and values that will be interpolated with piecewise linear functions
 82    """
 83
 84    function_dict = create_linear_interpolation_dict(times, values, variable_name="var")
 85    return _Function([{function_type: "var"}, function_dict])
 86
 87
 88def ensure_length_of_function_array(function_array: _List, length: int = 3):
 89    """Performs size check of a function array and appends the function array
 90    to the given length, if a list with only one item is provided.
 91
 92    Args:
 93        function_array: list with functions
 94        length: expected length of function array
 95
 96    Returns:
 97        function_array: list with functions with provided length
 98    """
 99
100    # extend items of function automatically if it is only provided once
101    if len(function_array) == 1:
102        function_array = function_array * length
103
104    if len(function_array) != length:
105        raise ValueError(
106            f"The function array must have length {length} not {len(function_array)}."
107        )
108    return function_array