File options.hxx¶

Defines

__OPTIONS_H__¶

OPTION(options, var, def)¶: Define for reading options which passes the variable name.

OPTION2(options, var1, var2, def)¶

OPTION3(options, var1, var2, var3, def)¶

OPTION4(options, var1, var2, var3, var4, def)¶

OPTION5(options, var1, var2, var3, var4, var5, def)¶

OPTION6(options, var1, var2, var3, var4, var5, var6, def)¶

VAROPTION(options, var, def)¶

BOUT_OVERRIDE_DEFAULT_OPTION(name, value)¶: Define for over-riding library defaults for options, should be called in global namespace so that the new default is set before main() is called.

Functions

template<> std::string as<std::string>(const std::string &similar_to) const: Specialised as routines.

std::string toString(const Options &value): Convert value to string.

template<class T, typename = bout::utils::EnableIfOptions<T>> inline std::ostream &operator<<(std::ostream &out, const T &value)¶

Output a stringified value to a stream

This is templated to avoid implict casting: anything is convertible to an Options, and we want exactly Options

class Options¶

#include <options.hxx>

Class to represent hierarchy of options.

Getting and setting values

Each Options object represents a collection of key-value pairs which can be used as a map.

Options options;

// Set values
options["key"] = 1.0;

// Get values. Throws BoutException if not found
int val = options["key"]; // Sets val to 1 

// Return as specified type. Throws BoutException if not found
BoutReal var = options["key"].as<BoutReal>();

// A default value can be used if key is not found
BoutReal value = options["pi"].withDefault(3.14);

// Assign value with source label. Throws if already has a value from same source
options["newkey"].assign(1.0, "some source");

// Force assign a new value
options["newkey"].force(2.0, "some source");

A legacy interface is also supported:

options.set("key", 1.0, "code"); // Sets a key from source "code"

int val;
options.get("key", val, 0); // Sets val to 1, default to 0 if not found

If a variable has not been set then the default value is used

int other;
options.get("otherkey", other, 2.0); // Sets other to 2 because "otherkey" not found

Conversion is performed silently:

options.set("value", "2.34", "here"); // Set a string

BoutReal value;
options.get("value", value, 0.0); // Sets value to 2.34

If a conversion cannot be done, then an exception is thrown

Sections

Each Options object can also contain any number of sections, which are themselves Options objects.

Options &section = options["section"];

which can be nested:

options["section"]["subsection"]["value"] = 3;

This always succeeds; if the section does not exist then it is created.

The legacy interface uses pointers:

Options *section = options.getSection("section");

e.g. options->getSection(“section”)->getSection(“subsection”)->set(“value”, 3);

Options also know about their parents:

Options &parent = section.parent();

or

Options *parent = section->getParent();

Root options object

For convenience, to avoid having to pass Options objects around everywhere, there is a global singleton Options object which can be accessed with a static function

Options &root = Options::root();

or

Options *root = Options::getRoot();

This is used to represent all the options passed to BOUT++ either in a file or on the command line.

Public Types

using ValueType = bout::utils::variant<bool, int, BoutReal, std::string, Field2D, Field3D, FieldPerp, Array<BoutReal>, Matrix<BoutReal>, Tensor<BoutReal>>¶: The type used to store values.

using ValuesMap = std::map<std::string, OptionValue>¶: Read-only access to internal options and sections to allow iteration over the tree

Public Functions

Options() = default¶: Constructor. This is called to create the root object.

inline Options(Options *parent_instance, std::string full_name)¶

Constructor used to create non-root objects

Parameters

parent – [in] Parent object
sectionName – [in] Name of the section, including path from the root

template<typename T> inline Options(T value)¶: Initialise with a value These enable Options to be constructed using initializer lists

Options(std::initializer_list<std::pair<std::string, Options>> values)¶

Construct with a nested initializer list This allows Options trees to be constructed, using a mix of types.

Example: { {“key1”, 42}, {“key2”, field} }

Options(const Options &other)¶: Copy constructor.

~Options() = default¶

inline bool hasAttribute(const std::string &key) const¶: Return true if this value has attribute key.

Options &operator[](const std::string &name)¶

Get a sub-section or value

Example:

Options parent; auto child = parent[“child”];

parent is now a section.

inline Options &operator[](const char *name)¶

const Options &operator[](const std::string &name) const¶: Get a sub-section or value If this object is not a section, or if name is not a child, then a BoutException will be thrown

inline const Options &operator[](const char *name) const¶

std::multiset<FuzzyMatch> fuzzyFind(const std::string &name, std::string::size_type distance = 4) const¶

Find approximate matches for name throughout the whole tree. distance controls the similarity of results

Returns a set of possible matches ordered by similarity to name. A distance of 1 means: a single insertion, deletion, substitution, or transposition; that the case differs, for example, “key” and “KEY” match with distance 1; or that an unqualified name matches a fully-qualified name, for example “key” matches “section:key” with distance 1. Note that “first:second:key” will not (closely) match “third:fourth:key”, but “key” will match both.

template<typename T> inline T operator=(T inputvalue)¶

Assignment from any type T Note: Using this makes this object a value.

Tries to stream the input to a std::stringstream and then saves the resulting string.

Options &operator=(const Options &other)¶

Copy assignment

This replaces the value, attributes and all children

Note that if only the value is desired, then that can be copied using the value member directly e.g. option2.value = option1.value;

template<typename T> inline void assign(T val, std::string source = "")¶

Assign a value to the option. This will throw an exception if already has a value

Example:

Options option; option[“test”].assign(42, “some source”);

Note: Specialised versions for types stored in ValueType

template<typename T> inline void force(T val, const std::string source = "")¶: Force to a value Overwrites any existing setting

bool isSet() const¶: Test if a key is set by the user. Values set via default values are ignored.

template<typename T, typename = typename std::enable_if_t<bout::utils::isVariantMember<T, ValueType>::value>> inline operator T() const¶

Cast operator, which allows this class to be assigned to type T. This is only allowed for types that are members of the ValueType variant. For other types, please use Options::as<T>()

Example:

Options option; option[“test”] = 2.0; int value = option[“test”];

template<typename T> inline T as(const T &similar_to = {}) const¶

Get the value as a specified type If there is no value then an exception is thrown Note there are specialised versions of this template for some types.

Example:

Options option; option[“test”] = 2.0; int value = option[“test”].as<int>();

An optional argument is an object which the result should be similar to. The main use for this is in Field2D and Field3D specialisations, where the Mesh and cell location are taken from this input.

template<typename T> inline T withDefault(T def)¶: Get the value of this option. If not found, set to the default value

inline std::string withDefault(const char *def)¶: Overloaded version for const char* Note: Different from template since return type is different to input

inline Options &withDefault(const Options &def)¶: Overloaded version to copy from another option.

template<typename T> inline T withDefault(T def) const¶: Get the value of this option. If not found, return the default value but do not set

template<typename T> inline T overrideDefault(T def)¶: Allow the user to override defaults set later, also used by the BOUT_OVERRIDE_DEFAULT_OPTION.

inline std::string overrideDefault(const char *def)¶: Overloaded version for const char* Note: Different from template since return type is different to input

inline Options &parent()¶: Get the parent Options object.

template<typename T> inline bool operator==(const T &other) const¶: Equality operator Converts to the same type and compares This conversion may fail, throwing std::bad_cast

bool operator==(const char *other) const¶: Overloaded equality operator for literal strings.

template<typename T> inline bool operator<(const T &other) const¶: Comparison operator.

bool operator<(const char *other) const¶: Overloaded comparison operator for literal strings.

template<typename T> inline void set(const std::string &key, T val, const std::string &source = "", bool force = false)¶

template<typename T> inline void forceSet(const std::string &key, T t, const std::string &source = "")¶

inline bool isSet(const std::string &key) const¶: Test if a key is set by the user. Values set via default values are ignored.

template<typename T, typename U> inline void get(const std::string &key, T &val, U def, bool log = false)¶: Get options, passing in a reference to a variable which will be set to the requested value.

template<typename T, typename U> inline void get(const std::string &key, T &val, U def, bool log = false) const¶

inline Options *getSection(const std::string &name)¶: Creates new section if doesn’t exist.

inline const Options *getSection(const std::string &name) const¶

inline Options *getParent() const¶

inline std::string str() const¶: Print string representation of this object and all sections in a tree structure

inline std::string name() const¶: Print just the name of this object without parent sections.

Options getUnused(const std::vector<std::string> &exclude_sources = {~~"Output"~~, ~~"user_default"~~}) const¶: Return a new Options instance which contains all the values not used from this instance. If an option has a “source” attribute in exclude_sources it is counted as having been used and so won’t be included in the returned value. By default, this is “Output” and “user_default” (used by overrideDefault).

void printUnused() const¶: Print the options which haven’t been used.

void setConditionallyUsed()¶: Set the attribute “conditionally used” to be true for options and all its children/sections, causing Options::getUnused to assume those options have been used. This is useful to ignore options when checking for typos etc.

ValuesMap values() const¶

std::map<std::string, const Options*> subsections() const¶

inline const std::map<std::string, Options> &getChildren() const¶

std::vector<std::string> getFlattenedKeys() const¶: Return a vector of all the full names of all the keys below this in the tree (not gauranteed to be sorted)

inline bool isValue() const¶: Return true if this is a value.

bool isSection(const std::string &name = "") const¶: Return true if this is a section.

inline bool valueUsed() const¶: If the option value has been used anywhere.

inline Options &doc(const std::string &docstring)¶: Set a documentation string as an attribute “doc” Returns a reference to this, to allow chaining

template<> inline void assign(bool val, std::string source)¶

template<> inline void assign(int val, std::string source)¶

template<> inline void assign(BoutReal val, std::string source)¶

template<> inline void assign(std::string val, std::string source)¶

template<> inline void assign(const char *val, std::string source)¶

template<> inline void assign(Field2D val, std::string source)¶

template<> inline void assign(Field3D val, std::string source)¶

template<> inline void assign(FieldPerp val, std::string source)¶

template<> inline void assign(Array<BoutReal> val, std::string source)¶

template<> inline void assign(Matrix<BoutReal> val, std::string source)¶

template<> inline void assign(Tensor<BoutReal> val, std::string source)¶

template<> int as(const int &similar_to) const¶

template<> BoutReal as(const BoutReal &similar_to) const¶

template<> bool as(const bool &similar_to) const¶

template<> Field2D as(const Field2D &similar_to) const¶

template<> Field3D as(const Field3D &similar_to) const¶

template<> FieldPerp as(const FieldPerp &similar_to) const¶

Public Members

ValueType value¶: The value stored.

std::map<std::string, AttributeType> attributes¶

A collection of attributes belonging to the value Special attributes:

time_dimension [string] If this is set then changes to the value do not need to be forced. The string will be used when writing the output as the name of the time dimension (unlimited first dimension in NetCDF files).
source [string] Describes where the value came from e.g. a file name, or “default”.
type [string] The type the Option is converted to when used.
doc [string] Documentation, describing what the variable does

Public Static Functions

static Options &root()¶: Get a reference to the only root instance.

static void cleanup()¶: Free all memory.

static inline Options *getRoot()¶: Get a pointer to the only root instance (singleton)

static void cleanCache()¶: clean the cache of parsed options

Private Functions

template<typename T> inline void _set_no_check(T val, std::string source)¶

template<typename T> inline void _set(T val, std::string source, bool force)¶

template<typename T> inline bool similar(T a, T b) const¶: Tests if two values are similar.

template<> inline bool similar(BoutReal a, BoutReal b) const¶: Specialised similar comparison methods.

Private Members

Options *parent_instance = {nullptr}¶

std::string full_name¶

bool is_section = true¶: Is this Options object a section?

std::map<std::string, Options> children¶: If a section then has children.

mutable bool value_used = false¶: Record whether this value is used.

Private Static Attributes

static const std::string DEFAULT_SOURCE = {_(~~"default"~~)}¶: The source label given to default values.

static Options *root_instance = {nullptr}¶: Only instance of the root section.

Friends

inline friend bool operator==(const Options &lhs, const Options &rhs)¶

class AttributeType : public mpark::variant<bool, int, BoutReal, std::string>¶

#include <options.hxx>

The type used to store attributes Extends the variant class so that cast operator can be implemented and assignment operator overloaded

Note: Due to default initialisation rules, if an attribute is used without being set, it will be false, 0, 0.0 and throw std::bad_cast if cast to std::string

Public Types

using Base = bout::utils::variant<bool, int, BoutReal, std::string>¶

Public Functions

AttributeType() = default¶: Constructor.

AttributeType(const AttributeType &other) = default¶: Copy constructor.

inline AttributeType(AttributeType &&other)¶: Move constructor.

~AttributeType() = default¶: Destructor.

inline AttributeType &operator=(const char *str)¶: Assignment from const char*.

template<typename T> inline operator T() const¶: Cast operator, which allows this class to be assigned to type T This will throw std::bad_cast if it can’t be done

template<typename T> inline T as() const¶: Get the value as a specified type This will throw std::bad_cast if it can’t be done

struct FuzzyMatch¶

#include <options.hxx>

Return type of Options::fuzzyFind

Public Members

const Options &match¶: The matching option.

std::string::size_type distance¶: Edit distance from original search term.

Friends

inline friend bool operator<(const FuzzyMatch &lhs, const FuzzyMatch &rhs)¶: Comparison operator so this works in a std::multiset.

struct OptionValue¶

#include <options.hxx>

Class used to store values, together with information about their origin and usage

Public Functions

inline OptionValue(std::string value, std::string source, bool used)¶: This constructor needed for map::emplace Can be removed in C++17 with map::insert and brace initialisation

Public Members

std::string value¶

std::string source¶

mutable bool used = false¶

template<> struct formatter<Options> : public bout::details::OptionsFormatterBase ¶

#include <options.hxx>

Format Options to string. Format string specification is:

‘d’: include ‘doc’ attribute if present
’i’: inline section names
’k’: only print the key, not the value
’s’: include ‘source’ attribute if present

namespace bout

Provides access to the Hypre library, handling initialisation and finalisation.

Usage

#include <bout/hyprelib.hxx>

class MyClass { public:

private: HypreLib lib; };

This will then automatically initialise Hypre the first time an object is created, and finalise it when the last object is destroyed.

Contact: Ben Dudson, bd512@york.ac.uk

This file is part of BOUT++.

BOUT++ is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

BOUT++ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with BOUT++. If not, see http://www.gnu.org/licenses/.

Information about the version of BOUT++

The build system will update this file on every commit, which may result in files that include it getting rebuilt. Therefore it should be included in as few places as possible

Information about the version of BOUT++

The build system will update this file at configure-time

SNB model

Functions

void checkForUnusedOptions()¶: Check if the global Options contains any unused keys and throw an exception if so. This check can be skipped by setting input:error_on_unused_options=false in the global Options.

void checkForUnusedOptions(const Options &options, const std::string &data_dir, const std::string &option_file)¶

Check if the given options contains any unused keys and throw an exception if so.

The error message contains helpful suggestions on possible misspellings, and how to automatically fix most common errors with library options. The data_dir and option_file arguments are used to customise the error message for the actual input file used

namespace details¶

struct OptionsFormatterBase¶

#include <options.hxx>

Implementation of fmt::formatter<Options> in a non-template class so that we can put the function definitions in the .cxx file, avoiding lengthy recompilation if we change it

Subclassed by fmt::formatter< Options >

Public Functions

auto parse(fmt::format_parse_context &ctx) -> fmt::format_parse_context::iterator¶

auto format(const Options &options, fmt::format_context &ctx) -> fmt::format_context::iterator¶

Private Members

bool docstrings = {false}¶: Include the ‘doc’ attribute, if present.

bool inline_section_names = {false}¶: If true, print variables as ‘section:variable’, rather than a section header ‘[section]’ and plain ‘variable’

bool key_only = {false}¶: Only include the key name, and not the value.

bool source = {false}¶: Include the ‘source’ attribute, if present.

std::string format_string¶: Format string to passed down to subsections.