CharacteristicMap.h

Go to the documentation of this file.

/****************************************************************************/
// Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
// Copyright (C) 2002-2024 German Aerospace Center (DLR) and others.
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0/
// This Source Code may also be made available under the following Secondary
// Licenses when the conditions for such availability set forth in the Eclipse
// Public License 2.0 are satisfied: GNU General Public License, version 2
// or later which is available at
// https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
/****************************************************************************/
// Characteristic map for vehicle type parameters as needed by the MMPEVEM model
// Teaching and Research Area Mechatronics in Mobile Propulsion (MMP), RWTH Aachen
/****************************************************************************/
 
 
/******************************************************************************
 * ============================= Example Usage ============================== *
 ******************************************************************************
 *                                                                            *
 * Assume a function f which maps from R^2 to R^1 according to...             *
 *                                                                            *
 *     |  0 |  1 |  2 |  3 |  4   -> x_1                                      *
 * ----|------------------------                                              *
 *  -1 |  1 |  3 |  1 | -2 |                                                  *
 *   1 |  1 | -2 | -3 |  7 |  5                                               *
 *   3 | -2 | -1 |  0 |  1 |  3                                               *
 *   5 |    |  0 |  8 |  4 |  4                                               *
 *                                                                            *
 *   |                                                                        *
 *   v                                                                        *
 *  x_2                                                                       *
 *                                                                            *
 * ... so that, for example, f(3, 1) = 7. Note that f is not defined at       *
 * (4, -1) and (0, 5). There are two ways to create a CharacteristicMap       *
 * object for this function.                                                  *
 * 1) Using the standard constructor:                                         *
 *      // Axes                                                               *
 *      std::vector<std::vector<double>> axes;                                *
 *      axes.push_back(std::vector<double>{0, 1, 2, 3, 4});  // Axis 1        *
 *      axes.push_back(std::vector<double>{-1, 1, 3, 5});    // Axis 2        *
 *      // Flattened row-major map entries                                    *
 *      std::vector<double> flattenedMap{1, 3, 1, -2, std::nan(""),           *
 *          1, -2, -3, 7, 5, -2, -1, 0, 1, 3, std::nan(""), 0, 8, 4, 4};      *
 *                                                                            *
 *      CharacteristicMap map1(2,              // Mapping from R^2...         *
 *                             1,              // ... to R^1                  *
 *                             axes,                                          *
 *                             flattenedMap);                                 *
 *                                                                            *
 * 2) Using a string-encoding of the map:                                     *
 *      CharacteristicMap map2("2,1|0,1,2,3,4;-1,1,3,5|1,3,1,-2,nan,"         *
 *          "1,-2,-3,7,5,-2,-1,0,1,3,nan,0,8,4,4");                           *
 *                                                                            *
 *    See below for an in-depth explanation of the format.                    *
 *                                                                            *
 *                                                                            *
 * To evaluate the map at, for instance, p = (2.2, 2), one must call:         *
 *   std::vector<double> res = map1.eval(std::vector<double>{2.2, 2},  // p   *
 *                                       1e-3);  // eps                       *
 *   if(std::isnan(res[0]))                                                   *
 *     std::cout << "[WARNING] Couldn't evaluate the map." << std::endl;      *
 *   else                                                                     *
 *     std::cout << "res = " << res[0] << std::endl;                          *
 *                                                                            *
 * The epsilon value is used for numerical reasons and decides how much a     *
 * point must deviate from its nearest neighbor before linear interpolation   *
 * is applied or when a point is considered outside of the map. The default   *
 * is 1e-6.                                                                   *
 *                                                                            *
 *                                                                            *
 * The string-encoding of a CharacteristicMap that maps from R^m to R^n is    *
 * formally defined as                                                        *
 *   "m,n|A_1[1],A_1[2],...,A_1[l1];A_2[1],A_2[2],...,A_2[l2];...;\           *
 *       A_m[1],A_m[2],...,A_m[lm]|\                                          *
 *       M_flat[1],M_flat[2],...,M_flat[l1*l2*...*lm]"                        *
 * where A_i[j] denotes the j-th value of the i-th axis (which has li values  *
 * total) and M_flat[i] stands for the i-th entry in the row-major flattened  *
 * map. To be more specific, given a map M, its flattened version is          *
 * computed as follows (using pseudo code):                                   *
 *   M_flat = ""                                                              *
 *   for i_m in {1,2,...,lm}:        // Last axis                             *
 *     ...                                                                    *
 *       for i_2 in {1,2,...,l2}:    // Second axis                           *
 *         for i_1 in {1,2,...,l1}:  // First axis (i.e. row axis)            *
 *           for d in {1,2,...,n}:   // Image dimensions                      *
 *             M_flat += M[i_1,i_2,...,i_m][d] + ","                          *
 *   removeTrailingComma(M_flat)                                              *
 *                                                                            *
 ******************************************************************************/
#pragma once
 
#include <vector>
#include <string>
 
 
class CharacteristicMap {
private:
    int domainDim;
 
    int imageDim;
 
    std::vector<std::vector<double>> axes;
 
    std::vector<double> flattenedMap;
 
    std::vector<int> strides;
 
    void determineStrides();
 
    int calcFlatIdx(const std::vector<int>& ref_idxs) const;
 
    int findNearestNeighborIdxs(const std::vector<double>& ref_p,
                                std::vector<int>& ref_idxs, double eps = 1e-6) const;
 
    std::vector<double> at(const std::vector<int>& ref_idxs) const;
 
 
 
public:
    CharacteristicMap(int domainDim, int imageDim,
                      const std::vector<std::vector<double>>& ref_axes,
                      const std::vector<double>& ref_flattenedMap);
 
    CharacteristicMap(const std::string& ref_mapString);
 
    std::string toString() const;
 
    int getDomainDim() const;
 
    int getImageDim() const;
 
    std::vector<double> eval(const std::vector<double>& ref_p,
                             double eps = 1e-6) const;
};