|
SCATMECH > Classes and Functions >
Utility >
Model
Abstract class Model
The class Model is an abstract class that all models in SCATMECH
inherit. It provides a number of run-time services to these models, including
- error handling,
- tools for passing values to model parameters and keeping track of changes,
- instantiation of new classes,
- providing lists of availble parameters, and
- providing information about parent and available child classes.
Include file:
#include "inherit.h"
Source code:
inherit.cpp
models.cpp
See also:
SCATMECH Home,
Inheritance,
Model_Ptr<model>
Definition of
public and protected elements:
class Model
{
public:
Model();
void AskUser();
void init();
void set_parameter(const std::string& name,const std::string& value);
void set_parameter(const std::string& name,const char* value);
template <class TYPE> void set_parameter(const std::string& parameter, const TYPE& value);
std::string get_parameter(const std::string& parameter) const;
void print_parameters(std::ostream& os,const std::string& prefex="") const;
void get_parameter_names(std::deque& plist) const;
ParameterInfo get_parameter_info(const std::string& parameter) const;
static Inheritance inheritance;
virtual const Inheritance& get_inheritance() const;
void set_recalc(int _recalc=0xFF);
virtual int get_recalc() const;
static void set_quiet(int _quiet);
static int get_quiet();
void SETUP();
protected:
virtual void setup();
virutal void set_parameter_base(const std::string& name,const std::string& value);
virtual std::string get_parameter_base(const std::string& parameter) const;
virtual void get_parameter_names_base(std::deque& plist, const std::string& prefix) const;
virtual void print_parameters_base(std::ostream& os,const std::string& prefex="") const;
void message(const std::string& s);
void error(const std::string& message);
int RECALC;
};
The function AskUser queries the user for all
parameters needed by the specific model, usually using the standard input (std::cin) and unbuffered output (std::cerr).
Top of Page
Function that sets all parameters to their default values.
Top of Page
void set_parameter(const std::string& name,const std::string& value)
void set_parameter(const std::string& name,const char* value)
template <class TYPE> void set_parameter(const std::string& parameter, const TYPE& value)
The virtual function set_parameter allows one to
change any model parameter by name. The string
name is the name of the parameter. For those
parameters that take their own subparameters, the parameter
name is followed by a period, followed by the subparameter's name.
In the first two functions, value contains the parameter
encoded as a string. If the parameter does not exist for the
current model, then an exception of type SCATMECH_exception is thrown. The third function converts value
to a string before sending that string to the model.
Example:
MicroroughnessBRDF_Model model;
model.set_parameter("substrate","(1.46,0.02)");
model.set_parameter("psd","ABC_PSD_Function");
model.set_parameter("psd.A",0.03);
Top of Page
string
get_parameter(const string& parameter)
Function that returns a string representation of a specific parameter. For numeric parameters, the
string representation of that value is returned. For pointers to models (i.e., Model_Ptr<model>), this
function returns the name of the model assigned to the parameter. Subparameters of those models can be accessed by using the "parameter.subparameter" notation.
Example:
MicroroughnessBRDF_Model model;
model.AskUser();
cout << model.get_parameter("substrate") << endl;
cout << model.get_parameter("psd") << endl;
cout << model.get_parameter("psd.A") << endl;
Top of Page
Function that prints a complete list of parameter names, current values, descriptions, and types to a stream.
Top of Page
Function that retrieves a list of all valid parameters for a given model. The data type StringList is a typedef for std::deque<std::string>.
The list (actually, a double-ended queue) contains all the valid input parameters that can be used in the above set_parameter and get_parameter functions.
Top of Page
ParameterInfo get_parameter_info(const string& parameter) const
Function that returns static information about a particular parameter. ParameterInfo is a structure defined as
struct ParameterInfo {
string name; // The name of the parameter...
string description; // A description of the parameter...
string type; // The data type for external programs...
string defaultvalue; // The default value for the parameter...
};
Top of Page
Every class inheriting Model has a static
member named inheritance of type Inheritance, which keeps track of all
models which inherit it and its parameters. It enables run-time generation
of instances of a class and dynamic access to parameters by name. Accessing a specific model's inheritance directly will
allow access to that specific model's parameters, but not those of a child model. Accessing the model's inheritance through the
function get_inheritance() will allow access to the parameters of the specific instantiation of the model. In the case of accessing
inheritance directly, one does not need an instance of the class, while in the case of using get_inheritance one needs an instance.
Top of Page
A private integer variable recalc is set whenever any
model parameter is modified. It signals that something has changed and that the function
setup() needs to be run. These functions provide access to recalc. The set_recalc performs
a bitwise OR with the current value of recalc.
If a model has parameters which are models in themselves (i.e., Model_Ptr<model>), the
model must override this function to call not only the parent's function get_recalc, but also each of
its model parameters' get_recalc.
Within setup(), the value of recalc should be accessed through the variable RECALC.
Top of Page
Many models provide progress indicators [using message()] that let the user know
what the model is working on. If one calls set_quiet(1), these messages will be disabled. They can
be turned back on with set_quiet(0). This function applies to all models.
Top of Page
The function setup() is called if the model is
evaluated with nonzero recalc. Any model that has one-time computations that can
enhance its performance when parameters have changed should override this function and provide those computations
it it. A model's setup() should always begin by calling its parent's
setup().
Top of Page
The function SETUP() should always be called at the beginning of
any model function that depends upon the parameters. It checks to see if recalc is nonzero. If so,
it will call the function setup().
Top of Page
The protected function message provides member models a means for communicating simple progress reports or warning messages.
If the value of quiet is true, then the message
will not be printed. The message, if quiet is false, will be printed to the standard error stream, by default.
Top of Page
void error(const std::string& s)
The protected function error will throw a SCATMECH_exception with text s. The exception text will also include the output of
print_parameters. This function should be used by all models to report errors.
Top of Page
These four protected virtual functions provide the functionality for the similarly-named public functions
set_parameter,
get_parameter,
set_parameter_names, and
print_parameters, respectively.
These functions do not normally need to be overridden. However, if the model has parameters that are
not recorded in the parameter database, these functions should be overridden. For example, Generic_Grating
has parameters that are dynamically determined at run-time.
Top of Page
For More Information
SCATMECH Technical Information and Questions
Sensor Science Division Home Page
Sensor Science Division Inquiries
Website Comments
Current SCATMECH version: 7.22 (April 2021)
|