Parameter

Raisin provides a global parameter tree. The root is available via ParameterContainer::getRoot(). Controllers and plugins that are dynamically loaded should use their injected paramRoot_ instead of calling getRoot() directly.

In the tree, nodes are either ParameterContainer (non-leaf) or Parameter (leaf) nodes. Use [] to navigate to a child ParameterContainer and () to access a Parameter. Missing nodes are created on first access.

Access patterns

container("name") creates or returns a parameter by name.
container("name", default_value) sets a default only if the parameter does not exist yet.
const container("name") requires the parameter to exist and will raise a fatal error if it does not, so use the default-value overload for optional parameters.

YAML format

loadFromPackageParameterFile(package_name, param_file_name) reads a YAML file from install/config/<package_name>/config/<param_file_name> and then overlays ~/.raisin/<package_name>/<param_file_name> if it exists. This allows local overrides without modifying installed files.

Parameters can be declared with value and dtype fields, with optional min, max, and options for validation:

test_string:
  value: hello
  dtype: string
  options: [hello, goodbye]
test_double:
  value: 5.3
  dtype: double
  min: 3
  max: 5
test_int:
  value: 3
  dtype: int
test_bool:
  value: true
  dtype: bool
test_vec_double:
  value: [1,2,3]
  dtype: vector<double>
test_vec_string:
  value: ["hello", "world"]
  dtype: vector<string>
test_vec_int:
  value: [1,2,3]
  dtype: vector<int>

Accepted dtype strings are string, double, bool, int, vector, vector<double>, vector<string>, and vector<int>. If you omit dtype and provide a plain scalar or sequence, the parameter uses UNDEFINED and can be cast to a compatible type at runtime, but you should be explicit for safety.

Validation notes

min and max must be specified together for scalar values; otherwise a fatal error is raised.
options are checked against the stringified value when assigning the parameter (operator=).
Validation is enforced during assignment; loading from YAML only sets the stored value.

For practical implementation examples, refer to the test_raisin_parameter.cpp.

// Copyright (c) 2020 Robotics and Artificial Intelligence Lab, KAIST
//
// Any unauthorized copying, alteration, distribution, transmission,
// performance, display or use of this material is prohibited.
//
// All rights reserved.

#include <gtest/gtest.h>

#include <string>

#include "../include/raisin_parameter/parameter_container.hpp"

//
// Tests
//

class Child {
 public:
  explicit Child(raisin::parameter::ParameterContainer& param): param_(param["Child"]) {
    param_("param1").setOptions({"hello", "goodbye"});
    param_("param1") = "hello";
    Eigen::VectorXd testVec(3);
    testVec << 1, 2, 3;
    param_("param2") = testVec;
    std::vector<std::string> testVecString = {"hello", "world"};
    param_("param3") = testVecString;
    std::vector<int> testVecInt = {1, 2, 3};
    param_("param4") = testVecInt;
  }

 private:
  raisin::parameter::ParameterContainer& param_;
};

class Parent {
 public:
  Parent()
      : param_(raisin::parameter::ParameterContainer::getRoot()),
        child_(raisin::parameter::ParameterContainer::getRoot()) {
    param_("param1") = 3;
    param_("param2") = true;
  }

 private:
  raisin::parameter::ParameterContainer& param_;
  Child child_;
};

TEST(ParameterTest, ParameterTest1) {
  Parent parent;
  auto& rootParamContainer = raisin::parameter::ParameterContainer::getRoot();
  EXPECT_EQ("hello", std::string(rootParamContainer["Child"]("param1")));
  EXPECT_EQ(3, int(rootParamContainer("param1")));
  EXPECT_EQ(true, bool(rootParamContainer("param2")));
  Eigen::VectorXd testVec = rootParamContainer["Child"]("param2");
  EXPECT_EQ(6, testVec.sum());
  std::vector<std::string> testVecString = rootParamContainer["Child"]("param3");
  EXPECT_EQ("hello", testVecString[0]);
  EXPECT_EQ("world", testVecString[1]);
  std::vector<int> testVecInt = rootParamContainer["Child"]("param4");
  EXPECT_EQ(6, testVecInt[0] + testVecInt[1] + testVecInt[2]);

  rootParamContainer["file"].loadFromPackageParameterFile("raisin_parameter", "params.yaml");

  EXPECT_EQ(5.3, double(rootParamContainer["file"]("test_double")));
  EXPECT_EQ("hello", std::string(rootParamContainer["file"]("test_string")));
  EXPECT_EQ(3, int(rootParamContainer["file"]("test_int")));
  EXPECT_EQ(true, bool(rootParamContainer["file"]("test_bool")));
  Eigen::VectorXd test_vec_true(3), test_vec_read(3);
  test_vec_true << 1, 2, 3;
  test_vec_read = rootParamContainer["file"]("test_vec_double");
  EXPECT_NEAR((test_vec_true - test_vec_read).sum(), 0, 1e-15);
  std::vector<double> test_vec_double_true = {1, 2, 3};
  std::vector<double> test_vec_double_read = rootParamContainer["file"]("test_vec_double");
  for (int i = 0; i < 3; i++) {
    EXPECT_NEAR(test_vec_double_true[i], test_vec_double_read[i], 1e-15);
  }
  std::vector<std::string> test_vec_string_true = {"hello", "world"};
  std::vector<std::string> test_vec_string_read = rootParamContainer["file"]("test_vec_string");
  for (int i = 0; i < 2; i++) {
    EXPECT_EQ(test_vec_string_true[i], test_vec_string_read[i]);
  }
  std::vector<int> test_vec_int_true = {1, 2, 3};
  std::vector<int> test_vec_int_read = rootParamContainer["file"]("test_vec_int");
  for (int i = 0; i < 3; i++) {
    EXPECT_EQ(test_vec_int_true[i], test_vec_int_read[i]);
  }
}

API

class ParameterContainer

Public Functions

Parameter &operator()(const std::string &name)

write version

Parameters:: name – name of the Parameter
Returns:: Parameter

Parameter &operator()(const std::string &name, const std::variant<int, double, const char*, std::string, bool, Eigen::VectorXd, std::vector<double>, std::vector<std::string>, std::vector<int>> &default_value)

write version with default value

Parameters:

name – name of the Parameter
default_value – default value

Returns:

Parameter

const Parameter &operator()(const std::string &name) const

read only version

Parameters:: name – name of the Parameter
Returns:: Parameter

ParameterContainer &operator[](const std::string &name)

Parameters:: name – name of the child ParameterContainer
Returns:: child ParameterContainer

std::shared_ptr<ParameterContainer> getChildSharedPointer(const std::string &name)

Parameters:: name – name of the child ParameterContainer
Returns:: shared pointer of child ParameterContainer

void loadFromPackageParameterFile(const std::string &package_name, const std::string &param_file_name = "params.yaml")

load parameters from yaml file

Parameters:

package_name – name of the package
package_file_name – name of the file inside the package(default is “params.yaml”)

std::unordered_map<std::string, std::shared_ptr<ParameterContainer>> &getParamContainerList()

Returns:: names of the child ParameterContainer

Public Static Functions

static ParameterContainer &getRoot()

Returns:: unique root of the parameterContainer

class Parameter

Public Types

enum class Dtype : int

parameter data types

Values:

enumerator STRING

enumerator DOUBLE

enumerator BOOL

enumerator INT

enumerator VECTOR_DOUBLE

enumerator VECTOR_STRING

enumerator VECTOR_INT

enumerator UNDEFINED

Public Static Functions

static inline std::string dTypeToString(Dtype dtype)

Parameters:: dtype – data type
Returns:: data type in string

static Dtype stringToDtype(const std::string &type)

Parameters:: type – data type in string
Returns:: data type in Dtype