Virtual Parameter Tree. This represents a tree of parameters read from some source but does not necessarily correspond to the parameters in the simulation itself or even to the simulation tree. This is meant to provide a hierarchical view into simulation parameters before they are actually applied to a real TreeNode tree. More...

#include <ParameterTree.hpp>

Classes
class	Node
	Node containing a Parameter and value to apply. Can be used to describes a value extracted from the tree when using get or tryGet. This is a copy of the value and is not in any way synchronized with the tree. More...

Public Member Functions
	ParameterTree ()
	Default Constructor.

	ParameterTree (const ParameterTree &rhp)

ParameterTree &	operator= (const ParameterTree &rhp)

virtual	~ParameterTree ()
	Destructor.

void	clear ()
	Clear all content from this tree.

bool	set (const std::string &path, const std::string &value, bool required, const std::string &origin="")
	Add a parameter to the tree, replacing any existing parameter.

Node *	create (const std::string &path, bool required=false)
	Add a node to the tree, with proper priority.

const Node &	get (const std::string &path) const
	Gets a node from the parameter tree while respecting parameter application order. In other words, getting through this method returns the latest value set for the parameter at the location described by path.

const Node &	operator[] (const std::string &name) const
	Gets a node form the parameter tree.

bool	hasValue (const std::string &path, const bool must_be_leaf=true) const
	Try to check if a node has value.

bool	exists (const std::string &path, const bool must_be_leaf=true) const
	Try to check if a node exists.

uint32_t	getUnreadValueNodes (std::vector< const Node * > *nodes) const
	Counts the number of values attached to the parameter tree which have values but have not been read. This is a smart system which looks at historical parameter values as well as the latest to be sure that all have been touched.

uint32_t	getUnreadValueNodes (std::vector< Node * > *nodes)
	Counts the number of values attached to the parameter tree which have values but have not been read. This is a smart system which looks at historical parameter values as well as the latest to be sure that all have been touched. non-const version.

const Node *	tryGet (const std::string &path, const bool must_be_leaf=true) const
	Try to get a node if it exists. Returns nullptr it it does not.

Node *	tryGet (const std::string &path, const bool must_be_leaf=true)
	tryGet non-const version

bool	isRequired (const std::string &path) const
	Recursively find first leaf node matching this pattern and decide if any node matching that node's pattern is required to exist in the SPARTA tree.

bool	unrequire (const std::string &path)
	Unrequire a node in the tree.

bool	isRead (const std::string &path) const
	Has a node with a given path been read.

Node const *	getRoot () const

Node *	getRoot ()

void	merge (const ParameterTree &rhp)
	Merge this tree with another by applying all of its parameters to this tree. Parameters in the right tree will override this tree's parameters if there are duplicate paths or overlapping patterns.

template<typename Callback >
size_t	visitNodes (Callback callback)
	Apply the given callback to all nodes.

template<typename Callback >
size_t	visitNodes (Callback callback) const
	Apply the given callback to all nodes.

template<typename Callback >
size_t	visitLeaves (Callback callback)
	Apply the given callback to all leaf nodes.

template<typename Callback >
size_t	visitLeaves (Callback callback) const
	Apply the given callback to all leaf nodes.

void	recursePrint (std::ostream &o, bool print_user_data=true) const
	Recursively print.

std::map< const Node , std::map< std::string, const TreeNode::ExtensionsBase > >	getAllNodeExtensions () const
	Get a mapping from Nodes to their extensions.

Detailed Description

Virtual Parameter Tree. This represents a tree of parameters read from some source but does not necessarily correspond to the parameters in the simulation itself or even to the simulation tree. This is meant to provide a hierarchical view into simulation parameters before they are actually applied to a real TreeNode tree.

Eventually, this structure will automatically share data with sparta::ParameterSet instances as they are created. For now, it is limited.

Typical use is to subclass this object for each simulator component/model which has a set of parameters it must consume. sparta::ParameterSet provides a generic interface through which config-file parsers or command-line parsers can populate the parameters from strings. Models that expose the ParameterSet full of sparta::Parameter instances should dynamic_cast a sparta::ParameterSet supplied to them at runtime back to a known type and operate through Parameters directly instead of through this generic interface.

Definition at line 42 of file ParameterTree.hpp.

Constructor & Destructor Documentation

◆ ParameterTree() [1/2]

sparta::ParameterTree::ParameterTree ( )

inline

Default Constructor.

Definition at line 1194 of file ParameterTree.hpp.

◆ ParameterTree() [2/2]

sparta::ParameterTree::ParameterTree ( const ParameterTree & rhp )

inline

Definition at line 1198 of file ParameterTree.hpp.

◆ ~ParameterTree()

virtual sparta::ParameterTree::~ParameterTree ( )

inlinevirtual

Destructor.

Definition at line 1216 of file ParameterTree.hpp.

Member Function Documentation

◆ clear()

void sparta::ParameterTree::clear ( )

inline

Clear all content from this tree.

Definition at line 1221 of file ParameterTree.hpp.

◆ create()

Node * sparta::ParameterTree::create	(	const std::string &	path,
		bool	required = false )

inline

Add a node to the tree, with proper priority.

Parameters

path	Path to create. TEMPORARY: Must not contain parent references (i.e. extra dots)
Are	the nodes added by this call required to exist?

Returns: TEMPORARY: Returns a Node if one is created or found, nullptr if not. May return nullptr if parameter path contains parent reference (any '.' character whicih is proceded by another '.' or the beginnign of the string). This will be fixed eventually. Nothing else should cause this to return nullptr

Setting is fundamentally different than getting in a virtual parameter tree. It cannot fail and (when setting with patterns [paths containing wildcards]), new nodes are almost always created.

Definition at line 1263 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ exists()

bool sparta::ParameterTree::exists	(	const std::string &	path,
		const bool	must_be_leaf = true ) const

inline

Try to check if a node exists.

Parameters

path	Path of the node to check
must_be_leaf	Check only if leaf node

Returns: Bool

Definition at line 1315 of file ParameterTree.hpp.

◆ get()

const Node & sparta::ParameterTree::get ( const std::string & path ) const

inline

Gets a node from the parameter tree while respecting parameter application order. In other words, getting through this method returns the latest value set for the parameter at the location described by path.

Parameters

path	Path of node to retrieve

Exceptions

SpartaException if node with given path does not exist (see exists)

Returns: Node at the given location. This node is temporary and becomes stale on any modification to this ParameterTree. Reading this node later may result in an incorrect value

Warning: The returned node should be considered stale when this ParameterTree is modified

Definition at line 1282 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ getAllNodeExtensions()

std::map< const Node *, std::map< std::string, const TreeNode::ExtensionsBase * > > sparta::ParameterTree::getAllNodeExtensions ( ) const

inline

Get a mapping from Nodes to their extensions.

Definition at line 1512 of file ParameterTree.hpp.

◆ getRoot() [1/2]

Node * sparta::ParameterTree::getRoot ( )

inline

Definition at line 1440 of file ParameterTree.hpp.

◆ getRoot() [2/2]

Node const * sparta::ParameterTree::getRoot ( ) const

inline

Definition at line 1438 of file ParameterTree.hpp.

◆ getUnreadValueNodes() [1/2]

uint32_t sparta::ParameterTree::getUnreadValueNodes ( std::vector< const Node * > * nodes ) const

inline

Counts the number of values attached to the parameter tree which have values but have not been read. This is a smart system which looks at historical parameter values as well as the latest to be sure that all have been touched.

Parameters

[out] nodes Nodes with unread values. This is not cleared

The implementation of this method is highly coupled with the tryGet() which marks read parameters (including historically set parameters) as read to satify this method

Definition at line 1330 of file ParameterTree.hpp.

◆ getUnreadValueNodes() [2/2]

uint32_t sparta::ParameterTree::getUnreadValueNodes ( std::vector< Node * > * nodes )

inline

Counts the number of values attached to the parameter tree which have values but have not been read. This is a smart system which looks at historical parameter values as well as the latest to be sure that all have been touched. non-const version.

Parameters

[out] nodes Nodes with unread values. This is not cleared

The implementation of this method is highly coupled with the tryGet() which marks read parameters (including historically set parameters) as read to satify this method

Definition at line 1345 of file ParameterTree.hpp.

◆ hasValue()

bool sparta::ParameterTree::hasValue	(	const std::string &	path,
		const bool	must_be_leaf = true ) const

inline

Try to check if a node has value.

Parameters

path	Path of the node to check
must_be_leaf	Check only if leaf node

Returns: Bool

Definition at line 1304 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ isRead()

bool sparta::ParameterTree::isRead ( const std::string & path ) const

inline

Has a node with a given path been read.

Parameters

[in] path Path to check

Resolves a path to any matching nodes (which may include any number of wildcard nodes) and checks that at least one of those nodes have been read 1 or more times.

Definition at line 1419 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ isRequired()

bool sparta::ParameterTree::isRequired ( const std::string & path ) const

inline

Recursively find first leaf node matching this pattern and decide if any node matching that node's pattern is required to exist in the SPARTA tree.

Definition at line 1372 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ merge()

void sparta::ParameterTree::merge ( const ParameterTree & rhp )

inline

Merge this tree with another by applying all of its parameters to this tree. Parameters in the right tree will override this tree's parameters if there are duplicate paths or overlapping patterns.

Note: This also copies all user data from the source ParameterTree into 'this'. User data will remain in the source tree (rhp).

Definition at line 1449 of file ParameterTree.hpp.

◆ operator=()

ParameterTree & sparta::ParameterTree::operator= ( const ParameterTree & rhp )

inline

Definition at line 1204 of file ParameterTree.hpp.

◆ operator[]()

const Node & sparta::ParameterTree::operator[] ( const std::string & name ) const

inline

Gets a node form the parameter tree.

Parameters

name	Name of parameter to retrieve

Definition at line 1294 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ recursePrint()

void sparta::ParameterTree::recursePrint	(	std::ostream &	o,
		bool	print_user_data = true ) const

inline

Recursively print.

Definition at line 1504 of file ParameterTree.hpp.

◆ set()

bool sparta::ParameterTree::set	(	const std::string &	path,
		const std::string &	value,
		bool	required,
		const std::string &	origin = "" )

inline

Add a parameter to the tree, replacing any existing parameter.

Parameters

path	Path (from root) to assign value
value	Value to assign to a path in this tree
required	Must this parameter exist?
origin	Origin of the value (e.g. "foo.yaml line:50 col:23")

Returns: TEMPORARY: Returns true of parameter is set, false if not. May return false if parameter path contains parent reference (any '.' character whicih is proceded by another '.' or the beginnign of the string). This will be fixed eventually.

Setting is fundamentally different than getting in a virtual parameter tree. It cannot fail and (when setting with patterns [paths containing wildcards]), new nodes are almost always created.

Definition at line 1239 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ tryGet() [1/2]

Node * sparta::ParameterTree::tryGet	(	const std::string &	path,
		const bool	must_be_leaf = true )

inline

tryGet non-const version

Parameters

path	Path of the node to retrieve

Returns: The node at the given path

Definition at line 1363 of file ParameterTree.hpp.

◆ tryGet() [2/2]

const Node * sparta::ParameterTree::tryGet	(	const std::string &	path,
		const bool	must_be_leaf = true ) const

inline

Try to get a node if it exists. Returns nullptr it it does not.

Parameters

path	Path of the node to retrieve

Returns: The node at the given path

Definition at line 1354 of file ParameterTree.hpp.

◆ unrequire()

bool sparta::ParameterTree::unrequire ( const std::string & path )

inline

Unrequire a node in the tree.

Parameters

path	The path to the node to unrequire (set ignore)

Returns: true if the node was found and set; false otherwise

Definition at line 1402 of file ParameterTree.hpp.

Here is the call graph for this function:

◆ visitLeaves() [1/2]

template<typename Callback >

size_t sparta::ParameterTree::visitLeaves ( Callback callback )

inline

Apply the given callback to all leaf nodes.

Template Parameters

Callback std::function<bool(Node*)> or equivalent lambda

Returns: Returns the total number of nodes visited

Note: The callback should return true if we should keep recursing, false to early return

Definition at line 1485 of file ParameterTree.hpp.

◆ visitLeaves() [2/2]

template<typename Callback >

size_t sparta::ParameterTree::visitLeaves ( Callback callback ) const

inline

Apply the given callback to all leaf nodes.

Template Parameters

Callback std::function<bool(const Node*)> or equivalent lambda

Returns: Returns the total number of nodes visited

Note: The callback should return true if we should keep recursing, false to early return

Definition at line 1497 of file ParameterTree.hpp.

◆ visitNodes() [1/2]

template<typename Callback >

size_t sparta::ParameterTree::visitNodes ( Callback callback )

inline

Apply the given callback to all nodes.

Template Parameters

Callback std::function<bool(Node*)> or equivalent lambda

Returns: Returns the total number of nodes visited

Note: The callback should return true if we should keep recursing, false to early return

Definition at line 1461 of file ParameterTree.hpp.

◆ visitNodes() [2/2]

template<typename Callback >

size_t sparta::ParameterTree::visitNodes ( Callback callback ) const

inline

Apply the given callback to all nodes.

Template Parameters

Callback std::function<bool(const Node*)> or equivalent lambda

Returns: Returns the total number of nodes visited

Note: The callback should return true if we should keep recursing, false to early return

Definition at line 1473 of file ParameterTree.hpp.

The documentation for this class was generated from the following file:

/github/workspace/sparta/sparta/simulation/ParameterTree.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ParameterTree() [1/2]

◆ ParameterTree() [2/2]

◆ ~ParameterTree()

Member Function Documentation

◆ clear()

◆ create()

◆ exists()

◆ get()

◆ getAllNodeExtensions()

◆ getRoot() [1/2]

◆ getRoot() [2/2]

◆ getUnreadValueNodes() [1/2]

◆ getUnreadValueNodes() [2/2]

◆ hasValue()

◆ isRead()

◆ isRequired()

◆ merge()

◆ operator=()

◆ operator[]()

◆ recursePrint()

◆ set()

◆ tryGet() [1/2]

◆ tryGet() [2/2]

◆ unrequire()

◆ visitLeaves() [1/2]

◆ visitLeaves() [2/2]

◆ visitNodes() [1/2]

◆ visitNodes() [2/2]