Rperesents a variable or outlet created and managed by an object in a simulation. More...

Public Types
enum	dsim_variable_usage { dsim_invalid_value = 0, dsim_parameter_value = 1, dsim_input_value = 2, dsim_output_value = 3, dsim_state_value = 4, dsim_integrated_value = 5 }
	Variable usage types. More...
Public Member Functions
	dsim_variable ()
	Default constructor.
	dsim_variable (const dsim_variable &base)
	Copy constructor.
dsim_variable &	operator= (const dsim_variable &base)
	Assignment operator.
bool	valid () const
	Returns whether or not this variable is valid.
dsim_variable::dsim_variable_usage	usage () const
	Returns the expected usage for this variable.
int	type () const
	Returns the type of this variable.
dsim_value	value () const
	Returns the current value of this variable, dependent on whether or not it is in co-integrated mode.
dsim_value	base_value () const
	Returns the current base value of this variable, even if it is in co-integrated mode.
dsim_value	cointegrated_value () const
	Returns the current co-integrated value of this, even it if is not in co-integrated mode.
void *	raw_value () const
	Returns the raw pointer for the value held by this variable.
bool	extract_raw_value (void *destination) const
	Copies the raw value of the variable into a provided location.
const char *	units () const
	Returns the units assigned to this variable.
const char *	description () const
	Returns the human-readable description of this variable.
int	nominal_rows () const
	Returns the nominal number of rows for values held by this variable.
int	nominal_columns () const
	Returns the nominal number of columns for values held by this variable.
void	set_nominal_dimensions (int rows, int columns)
	Change the nominal rows and columns for values held by this variable.
bool	cointegrated () const
	Returns whether or not the object is in co-integrated mode.
void	set_cointegrated (bool flag)
	Sets whether or not the object is in co-integrated mode.
int	value_as_int () const
	Returns the current value of this variable as an integer.
void	set_value_as_int (int val)
	Sets the current value of this variable as an integer.
double	value_as_double () const
	Returns the current value of this variable as a double.
void	set_value_as_double (double val)
	Sets the current value of this variable as a double.
ml_matrix	value_as_matrix () const
	Returns the current value of this variable as a matrix.
void	set_value_as_matrix (const ml_matrix &val)
	Sets the current value of this variable as a matrix.
const char *	value_as_string () const
	Returns the current value of this variable as a string.
void	set_value_as_string (const char *val)
	Sets the current value of this variable as a string.
void	set_value (int type, void *new_value)
	Sets the current value of this variable by providing a data type and a raw value pointer.
void	set_value (const dsim_value &new_value)
	Sets the current value of this variable to the provided value.
void	set_derivative (int type, void *deriv) throw (dsim_type_mismatch_exception)
	Sets the current derivative of this variable by providing a data type and a raw value pointer.
void	set_derivative (const dsim_value &deriv) throw (dsim_type_mismatch_exception)
	Sets the current derivative of this variable by providing a value.
dsim_value	derivative () const
	Returns the current derivative of this variable.
void *	integration_ptr ()
	Retrieve the stored integration pointer for this variable.
void	set_integration_ptr (void *ptr)
	Store an integration pointer in this variable.
void	set_attribute (const std::string &name, const std::string &value)
	Sets an attribute for this variable.
bool	has_attribute (const std::string &name)
	Tests whether or not a variable has a specific attribute.
std::string	get_attribute (const std::string &name)
	Gets the value of an attribute.
std::map< std::string, std::string >::iterator	attribute_iterator ()
	Gets the starting iterator for the attributes at this variable.
std::map< std::string, std::string >::iterator	end_attribute_iterator ()
	Gets the ending iterator for the attributes at this variable.
void	mark_telemetry ()
	Marks this variable as telemetry.
void	mark_command ()
	Marks this variable as a command.
void	mark_command_and_telemetry ()
	Marks this variable as both a command and telemetry.
void	mark_telemetry_and_command ()
	Marks this variable as both a command and telemetry.
bool	is_telemetry () const
	Tests whether or not this variable has been marked as telemetry.
bool	is_command () const
	Tests whether or not this variable has been marked as a command.
bool	has_changed () const
	Indicates whether or not the value of this variable has changed.
void	mark_unchanged ()
	Clears the has-changed flag for this variable.

Detailed Description

Rperesents a variable or outlet created and managed by an object in a simulation.

Variables are the primary data storage and propagation mechanism within DSim. Objects create dsim_variable objects, look up variables at other objects in the simulation, and read and set the values of those variables.

All variables have a specific data type that they store. For those variables which are integrated states, the variables actually store the data twice- once for the base value that is updated each timestep, and once for the co-integrated version of the value, which may be updated many times each timestep according to the variable's integrator. Objects can choose to work with the co-integrated version of the variable by calling set_cointegrated().

Variables may or may not be valid at a certain time. A dsim_variable object that is freshly created is in an invalid state; it can be made valid if a valid dsim_variable is assigned to it, usually from either a variable lookup or a variable creation function call at dsim_model. The validity of a variable can (and should) be checked with the valid() function call.

Member Enumeration Documentation

enum dsim_variable::dsim_variable_usage

Variable usage types.

Variables have a usage associated with them. With the exception of the dsim_integrated_value usage, these usages are merely hints to the system and to users as to the purpose of the variable; they have no effect on how the variable operates. Each usage (except for invalid) matches one of the create_* functions of dism_model. See those functions for more information.

Enumerator:

dsim_invalid_value	Invalid variables have this usage.
dsim_parameter_value	The variable represents a model parameter, and generally is expected to be set in the setup file and not change over the lifetime of the object.
dsim_input_value	The variable represents an input to the object, and it is expected that its value will be set by external entities and read by the creating object.
dsim_output_value	The variable represents an output from the object, and it is expected that its value will be set by the object and then read by external entities.
dsim_state_value	The variable represents object state that will be updated and used by the object over its lifetime. External entities may read the value but are generally not expected to change it.
dsim_integrated_value	The variable represents object state that will be integrated and updated each timestep. External entities may read the value are generally not expected to change it.

Member Function Documentation

std::map< std::string, std::string >::iterator dsim_variable::attribute_iterator ( )

Gets the starting iterator for the attributes at this variable.

Returns the starting iterator for the map of attributes, suitable for use in iterating over the attributes of the variable.

Returns:: The begin() iterator for the map.

dsim_value dsim_variable::base_value ( ) const

Returns the current base value of this variable, even if it is in co-integrated mode.

Returns:: The base value of this variable, regardless of whether or not the variable is currently in co-integrated mode.

dsim_value dsim_variable::cointegrated_value ( ) const

Returns the current co-integrated value of this, even it if is not in co-integrated mode.

Returns:: The co-integrated value of this variable, regardless of whether or not the variable is currently in co-integrated mode. If the variable does not represent an integrated state, the co-integrated value is undefined.

dsim_value dsim_variable::derivative ( ) const

Returns the current derivative of this variable.

Returns:: The current derivative stored in the variable. If no derivative has been stored, the value is undefined. If the variable is not valid, returns an invalid dsim_value().

const char * dsim_variable::description ( ) const

Returns the human-readable description of this variable.

Returns:: The description string provided when the variable was set up. If the variable is not valid, returns an empty string ("").

std::map< std::string, std::string >::iterator dsim_variable::end_attribute_iterator ( )

Gets the ending iterator for the attributes at this variable.

Returns the ending iterator for the map of attributes, suitable for use as the end condition of a loop over the attributes of an variable.

Returns:: The end() iterator for the map.

bool dsim_variable::extract_raw_value ( void * destination ) const

Copies the raw value of the variable into a provided location.

Parameters:

destination A pointer to the location to which the value should be copied. The destination must hold the appropriate amount of space for a value of the type held by the variable.

Returns:: If the variable is not valid, which is the only detectable error condition, false will be returned and nothing will be written to destination. Otherwise, true will be returned.

std::string dsim_variable::get_attribute ( const std::string & name )

Gets the value of an attribute.

Returns the string value associated with the requested attribute.

Parameters:

name	The name of the attribute to look up.

Returns:: The value for the requested attribute, or an empty string if the attribute does not exist. If you need to distinquish non-existence with empty-string values, use the has_attribute() function.

bool dsim_variable::has_attribute ( const std::string & name )

Tests whether or not a variable has a specific attribute.

Determines whether or not an attribute with a specific name has been set for this object.

Parameters:

name	The name of the attribute.

Returns:: Returns true if an attribute with the given name has been set, or false if not.

bool dsim_variable::has_changed ( ) const

Indicates whether or not the value of this variable has changed.

Each variable keeps a has-changed flag, which is set to true whenever the value of the variable is modified. The flag is not cleared at any time by DSim itself, and its use is generally confined to external entities running DSim simulations.

Note that a variable is "changed" if any of the value setting functions have been called on it, even if they are not setting a distinct value.

Returns:: The current value of the has-changed flag, or false if this variable is not valid.

void * dsim_variable::integration_ptr ( )

Retrieve the stored integration pointer for this variable.

This function is intended to be called only by the integrator instance responsible for this variable.

Returns:: The currently stored integration pointer for this variable, or NULL if no integration pointer has been set or the variable is invalid

bool dsim_variable::is_command ( ) const

Tests whether or not this variable has been marked as a command.

Returns:: True if the command flag has been set, or false if not.

bool dsim_variable::is_telemetry ( ) const

Tests whether or not this variable has been marked as telemetry.

Returns:: True if the telemetry flag has been set, or false if not.

void dsim_variable::mark_command ( )

Marks this variable as a command.

The command flag for a variable has no meaning for DSim; it exists to allow variables to have special meaning for an external application running the simulation.

void dsim_variable::mark_command_and_telemetry ( )

Marks this variable as both a command and telemetry.

Marks as both telemetry and command

void dsim_variable::mark_telemetry ( )

Marks this variable as telemetry.

The telemetry flag for a variable has no meaning for DSim; it exists to allow variables to have special meaning for an external application running the simulation.

void dsim_variable::mark_unchanged ( )

Clears the has-changed flag for this variable.

After a change has been noted, the has-changed flag should generally be cleared via this method to ensure that subsequent changes can be detected.

int dsim_variable::nominal_columns ( ) const

Returns the nominal number of columns for values held by this variable.

Variables are given a nominal number of columns during creation. This number is only a guide- values stored in the variable are not required to match the nominal number of columns.

Returns:: The provided nominal number of columns for the variable, or 1 if the variable is not valid.

int dsim_variable::nominal_rows ( ) const

Returns the nominal number of rows for values held by this variable.

Variables are given a nominal number of rows during creation. This number is only a guide- values stored in the variable are not required to match the nominal number of rows.

Returns:: The provided nominal number of rows for the variable, or 1 if the variable is not valid.

void * dsim_variable::raw_value ( ) const

Returns the raw pointer for the value held by this variable.

Returns:: The raw data pointer for the data stored in the variable. If the variable is not valid, returns NULL.

void dsim_variable::set_attribute	(	const std::string &	name,
		const std::string &	value
	)

Sets an attribute for this variable.

Sets the value associated with a named attribute, creating that attribute if it does not yet exist.

Parameters:

name	The name of the attribute.
value	The value to associate with the attribute.

void dsim_variable::set_derivative	(	int	type,
		void *	deriv
	)		throw (dsim_type_mismatch_exception)

Sets the current derivative of this variable by providing a data type and a raw value pointer.

Sets the current derviative for the variable, which will be used by the variable's integrator. If the type provided does not match the type of the variable, a dsim_type_mismatch_exception will be thrown.

Parameters:

type	The type of the provided derivative value.
deriv	A pointer to the derivative value.

void dsim_variable::set_derivative ( const dsim_value & deriv ) throw (dsim_type_mismatch_exception)

Sets the current derivative of this variable by providing a value.

Sets the current derviative for the variable, which will be used by the variable's integrator. If the type provided does not match the type of the variable, a dsim_type_mismatch_exception will be thrown.

Parameters:

deriv The value to set as the derivative.

void dsim_variable::set_integration_ptr ( void * ptr )

Store an integration pointer in this variable.

This function is intended to be called only by the integrator instance responsible for this variable.

When a new integration pointer is set, the previous pointer is discarded.

Parameters:

ptr	The new pointer to store with the variable.

void dsim_variable::set_nominal_dimensions	(	int	rows,
		int	columns
	)

Change the nominal rows and columns for values held by this variable.

Variables are given a nominal number of rows and columns during creation. These numbers are only a guide- values stored in the variable are not required to match the nominal number of columns. This function allows the nominal dimensions of the variable to be changed.

Parameters:

rows	The new nominal number of rows
columns	The new nominal number of columns

void dsim_variable::set_value	(	int	type,
		void *	new_value
	)

Sets the current value of this variable by providing a data type and a raw value pointer.

Attempts to set the value of the variable to a new value provided via pointer and of the specified type. If the provided type does not match the the type of the variable, the provided value will be converted, if possible, to the type of the variable. If the conversion attempt fails, the set will fail.

Parameters:

type	The type of the value pointed to by new_value.
new_value	A pointer to the value to be stored in the variable.

void dsim_variable::set_value ( const dsim_value & new_value )

Sets the current value of this variable to the provided value.

Attempts to set the value of the variable to a new value provided via pointer and of the specified type. If the provided type does not match the the type of the variable, the provided value will be converted, if possible, to the type of the variable. If the conversion attempt fails, the set will fail.

Parameters:

new_value The value to be stored in the variable.

void dsim_variable::set_value_as_double ( double val )

Sets the current value of this variable as a double.

Attempts to set the value of the variable to a double. If the variable's data type is not sd_type_double, the double value provided will first be converted, if possible, to the data type of the variable; if it cannot be, the set will fail.

Parameters:

val	The double value to store in the variable

void dsim_variable::set_value_as_int ( int val )

Sets the current value of this variable as an integer.

Attempts to set the value of the variable to an integer. If the variable's data type is not sd_type_int, the integer value provided will first be converted, if possible, to the data type of the variable; if it cannot be, the set will fail.

Parameters:

val	The integer value to store in the variable

void dsim_variable::set_value_as_matrix ( const ml_matrix & val )

Sets the current value of this variable as a matrix.

Attempts to set the value of the variable to a matrix. If the variable's data type is not sd_type_matrix, the matrix value provided will first be converted, if possible, to the data type of the variable; if it cannot be, the set will fail.

Parameters:

val	The matrix value to store in the variable

void dsim_variable::set_value_as_string ( const char * val )

Sets the current value of this variable as a string.

Attempts to set the value of the variable to a string. If the variable's data type is not sd_type_string, the string value provided will first be converted, if possible, to the data type of the variable; if it cannot be, the set will fail.

Parameters:

val	The string value to store in the variable

int dsim_variable::type ( ) const

Returns the type of this variable.

Returns:: The type of the data stored in the variable. If the variable is not valid, returns sd_type_invalid.

const char * dsim_variable::units ( ) const

Returns the units assigned to this variable.

Returns:: The units string provided when the variable was set up. If the variable is not valid, returns an empty string ("").

dsim_variable::dsim_variable_usage dsim_variable::usage ( ) const

Returns the expected usage for this variable.

Returns:: The usage specified for this variable. If the variable is not valid, returns dsim_invalid_value.

dsim_value dsim_variable::value ( ) const

Returns the current value of this variable, dependent on whether or not it is in co-integrated mode.

The value referenced by this function depends on whether or not this variable is currently in co-integrated mode. If so, it will return the current cointegrated value; if not, it will return the current base value.

Returns:: The value stored in the variable, or an invalid value object if the variable is not valid.

double dsim_variable::value_as_double ( ) const

Returns the current value of this variable as a double.

If the variable's type is not sd_type_double, the value in the variable will be converted to a double and returned.

Returns:: The double value of the variable, or 0.0 if the variable is invalid or the value cannot be converted to a double.

int dsim_variable::value_as_int ( ) const

Returns the current value of this variable as an integer.

If the variable's type is not sd_type_int, the value in the variable will be converted to an integer and returned.

Returns:: The integer value of the variable, or 0 if the variable is invalid or the value cannot be converted to an integer.

ml_matrix dsim_variable::value_as_matrix ( ) const

Returns the current value of this variable as a matrix.

If the variable's type is not sd_type_matrix, the value in the variable will be converted to a matrix and returned.

Returns:: The matrix value of the variable, or an empty matrix if the variable is invalid or the value cannot be converted to a matrix.

const char * dsim_variable::value_as_string ( ) const

Returns the current value of this variable as a string.

If the variable's type is not sd_type_string, the value in the variable will be converted to a string and returned.

Returns:: The string value of the variable, or NULL if the variable is invalid or the value cannot be converted to a double.

dsim_variable Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation