Model Data Management

dsim_model member functions that provide variable and outlet creation and lookup functionality. More...

Functions
dsim_variable	dsim_model::create_parameter (const char *name, int data_type, void *init_value, int rows, int cols, const char *units, const char *description)
	Create a new variable that will be marked for usage as a parameter.
dsim_variable	dsim_model::create_input (const char *name, int data_type, void *init_value, int rows, int cols, const char *units, const char *description)
	Create a new variable that will be marked for usage as an input.
dsim_variable	dsim_model::create_output (const char *name, int data_type, void *init_value, int rows, int cols, const char *units, const char *description)
	Create a new variable that will be marked for usage as an output.
dsim_variable	dsim_model::create_state (const char *name, int data_type, void *init_value, int rows, int cols, const char *units, const char *description)
	Create a new variable that will be marked for usage as a state.
dsim_variable	dsim_model::create_integrated_state (const char *name, int data_type, void *init_value, int rows, int cols, const char *units, const char *description)
	Create a new variable that will be marked for usage as an integrated state.
void	dsim_model::create_outlet (dsim_variable &outlet, const char *name, int data_type, const char *units, const char *description, bool dependent=false)
	Create an outlet to which a variable will be connected in a setup file.
dsim_variable	dsim_model::request_variable (const char *path, bool quiet=false, bool store=true)
	Request a variable created elsewhere in the simulation.
dsim_variable	dsim_model::request_hierarchy_variable (const char *path, bool quiet=false)

---

Detailed Description

dsim_model member functions that provide variable and outlet creation and lookup functionality.

Variables and outlets form the heart of objects and simulations. Objects create variables to store their parameters and states, and then update those variables as the simulation progresses. Objects can request variables created at other objects, to allow inter-object interaction; for instance, a spring object would need to get the position of the mass attached to the spring in order to calculate the force to be applied to the mass. The object representing the mass, then, would have a position variable that would probably be integrated at each timestep.

Each variable has a specific usage associated with it which acts as a hint to DSim and to external users about the purpose of the variable. For the most part, this usage has no practical effect on the variable; the exception is the "integrated state" usage, created with create_integrated_state(), which causes the variable to be registered with the object's integrator.

In addition to creating variables, objects may have outlets, which act as indirect references to a variable that will be found elsewhere. When a simulation is set up, the setup file will specify which variable the outlet will actually be connected to. Once connected, the object can use the outlet as if it were any other variable. This allows the object's interaction with other parts of the simulation to easily be customized for each simulation.

---

Function Documentation

dsim_variable dsim_model::create_input	(	const char *	name,
		int	data_type,
		void *	init_value,
		int	rows,
		int	cols,
		const char *	units,
		const char *	description
	)		[protected, inherited]

Create a new variable that will be marked for usage as an input.

Create a new variable at this object, with its usage marked as "input".

Parameters:

name	The name to give the new variable. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this variable, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string.
init_value	A pointer to the initial value for the variable, which should match the data type provided. For instance, if the data type is sd_type_double, a pointer to a double containing the initial value should be provided as the init_value parameter.
rows	The number of rows nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
cols	The number of columns nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when an outlet is connected to a variable, the units for the outlet and variable are checked against each other.
description	A human-readable description of the purpose of this variable, used to provide information to a user setting up the smulation.

Returns:

The created variable, which should be stored in a member variable.

dsim_variable dsim_model::create_integrated_state	(	const char *	name,
		int	data_type,
		void *	init_value,
		int	rows,
		int	cols,
		const char *	units,
		const char *	description
	)		[protected, inherited]

Create a new variable that will be marked for usage as an integrated state.

Create a new variable at this object, with its usage marked as "integrated state". In addition, the variable will be registered with the object's integrator, and object will be configured to have rhs() called on it. (See configure_timestep() for more information.)

Parameters:

name	The name to give the new variable. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this variable, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string.
init_value	A pointer to the initial value for the variable, which should match the data type provided. For instance, if the data type is sd_type_double, a pointer to a double containing the initial value should be provided as the init_value parameter.
rows	The number of rows nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
cols	The number of columns nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when an outlet is connected to a variable, the units for the outlet and variable are checked against each other.
description	A human-readable description of the purpose of this variable, used to provide information to a user setting up the smulation.

Returns:

The created variable, which should be stored in a member variable.

void dsim_model::create_outlet	(	dsim_variable &	outlet,
		const char *	name,
		int	data_type,
		const char *	units,
		const char *	description,
		bool	dependent = false
	)		[protected, inherited]

Create an outlet to which a variable will be connected in a setup file.

Create a new outlet at this object, associated with a provided dsim_variable. Outlets can then be connected to variables at run-time, usually via the simulation setup file, to allow the source (or target) of data for this object to be configurable.

Parameters:

outlet	The dsim_variable object that will be turned into an outlet. The variable will be adjusted to point at the appropriate remote variable when the outlet is connected to a source.
name	The name to give the new outlet. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this outlet, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string. When the outlet is connected to a source variable, the data types of the outlet and source are compared and a warning is emitted if they differ.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when the outlet is connected to a variable, the units for the outlet and variable are checked against each other and a warning is emitted if they differ.
description	A human-readable description of the purpose of this outlet, used to provide information to a user setting up the smulation.
dependent	An optional parameter. When present and true, this object will automatically have a dependency set up on the object that provides the source for this outlet.

dsim_variable dsim_model::create_output	(	const char *	name,
		int	data_type,
		void *	init_value,
		int	rows,
		int	cols,
		const char *	units,
		const char *	description
	)		[protected, inherited]

Create a new variable that will be marked for usage as an output.

Create a new variable at this object, with its usage marked as "output".

Parameters:

name	The name to give the new variable. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this variable, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string.
init_value	A pointer to the initial value for the variable, which should match the data type provided. For instance, if the data type is sd_type_double, a pointer to a double containing the initial value should be provided as the init_value parameter.
rows	The number of rows nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
cols	The number of columns nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when an outlet is connected to a variable, the units for the outlet and variable are checked against each other.
description	A human-readable description of the purpose of this variable, used to provide information to a user setting up the smulation.

Returns:

The created variable, which should be stored in a member variable.

dsim_variable dsim_model::create_parameter	(	const char *	name,
		int	data_type,
		void *	init_value,
		int	rows,
		int	cols,
		const char *	units,
		const char *	description
	)		[protected, inherited]

Create a new variable that will be marked for usage as a parameter.

Create a new variable at this object, with its usage marked as "parameter".

Parameters:

name	The name to give the new variable. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this variable, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string.
init_value	A pointer to the initial value for the variable, which should match the data type provided. For instance, if the data type is sd_type_double, a pointer to a double containing the initial value should be provided as the init_value parameter.
rows	The number of rows nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
cols	The number of columns nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when an outlet is connected to a variable, the units for the outlet and variable are checked against each other.
description	A human-readable description of the purpose of this variable, used to provide information to a user setting up the smulation.

Returns:

The created variable, which should be stored in a member variable.

dsim_variable dsim_model::create_state	(	const char *	name,
		int	data_type,
		void *	init_value,
		int	rows,
		int	cols,
		const char *	units,
		const char *	description
	)		[protected, inherited]

Create a new variable that will be marked for usage as a state.

Create a new variable at this object, with its usage marked as "state".

Parameters:

name	The name to give the new variable. The name should contain no spaces, and cannot contain the colon (:) or pipe (|) characters. Also, names of variables at a single object must be unique.
data_type	The data type for this variable, typically one of sd_type_int, sd_type_double, sd_type_matrix or sd_type_string.
init_value	A pointer to the initial value for the variable, which should match the data type provided. For instance, if the data type is sd_type_double, a pointer to a double containing the initial value should be provided as the init_value parameter.
rows	The number of rows nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
cols	The number of columns nominally contained in this variable. Only meaningful if the variable is of type sd_type_matrix.
units	The units for this variable, if appropriate. Used to provide information to the user setting up the simulation; also, when an outlet is connected to a variable, the units for the outlet and variable are checked against each other.
description	A human-readable description of the purpose of this variable, used to provide information to a user setting up the smulation.

Returns:

The created variable, which should be stored in a member variable.

dsim_variable dsim_model::request_hierarchy_variable	(	const char *	path,
		bool	quiet = false
	)		[protected, inherited]

Request a variable anywhere within the simulation.

Parameters:

path	The path to the variable.
quiet	If true, suppresses showing a warning if a variable with the specified path does not exist.

Returns:

The variable, if one existed at the provided path. If not, an invalid dsim_variable will be returned and a warning will be emitted.

dsim_variable dsim_model::request_variable	(	const char *	path,
		bool	quiet = false,
		bool	store = true
	)		[protected, inherited]

Request a variable created elsewhere in the simulation.

Request a variable anywhere within the simulation.

Parameters:

path	The path to the variable.
quiet	If true, suppresses showing a warning if a variable with the specified path does not exist.
store	If true, the variable will be cached locally

Returns:

The variable, if one existed at the provided path. If not, an invalid dsim_variable will be returned and a warning will be emitted.