DPCM: Default property change monitoring for MatLab class properties. More...

Detailed Description

DPCM: Default property change monitoring for MatLab class properties.

This class collection allows to automatically supervise changes to properties' default settings and create reports of different detail and level for them.

The purpose of this tool is to improve the reliability and quality of small software tools or even frameworks by ensuring that any end-users of the software get appropriate warnings when NOT changing default values, whose values have been chosen to the best knowledge of the programmers/developers but still might be critical or of great importance for the outcome of the computation.

Target group is any MatLab programmer who develops classes and functionalities (e.g. simulation- or discretization tools, solvers etc) that are used by different people who might lack the domain knowledge of the program at hand.

Roughly, the idea is to register any publicly changeable property after setting the default values and process any changes made to the properties at a later stage (by using the SetObservable flag for MatLab classes)

Example: Create a DPCMDemoClass instance and run the demo! dc = DPCMDemoClass; dc.demo; % Watch out, there are pauses included! :-)

The monitoring system distinguishes between several classes of properties that allow for a more precise categorization.

DPCM property classes

Critical A critical property is vital for the algorithm performance and result. This might be a given accuracy level or the consistency order for a discretization scheme. Any critical properties should have been set or at least validated by the end-user before simulations are started, otherwise a well-noticeable warning is issued.
Important Important properties are next in the order after the critical level. The difference is that those properties have an influence on the overall result, but will not lead to a totally different quality of the algorithm result. This might be an explicit jacobian matrix which would otherwise be computed by finite differences, a number of different samples to take or the simulation end time which is of course important for the computational time needed but does not affect the simulation quality. If any important properties have not been changed from their default value, a notice appears before the simulation.
alglimit Algorithm limit properties are of fail-safe nature. Sometimes algorithms have stopping conditions that are checked for within iterations which usually stop when some prescribed accuracy is gained. However, if an algorithm does not reach such states a maximum number of iterations can be put in place to force abortion of the iterations. As those properties are supposed to have appropriate (=high enough) default values simulations can be started without changing them. However, presence of those properties almost always implies the presence of a critical property like an accuracy level which is the first algorithm stopping condition.
scaling Scaling properties are used to perform numerical scaling of time, space or states within a numerical simulation. They are of an optional nature and thus are not elemental for simulations to produce accuracte results. However, for this special level it might very well be important if some scaling properties are set and some others are not. This might lead to wrong computational results and thus a warning is issued if not all or none of those properties are changed.
optional Optional properties are, well, optional. They can refer to whole components of a simulation that can be plugged in or not, specify a custom behaviour which will otherwise be computed in a correct but possibly more ineffective way or simply set the name of a component.
data Data properties circumfence all properties that must be set (or even will be set by the framework) at some stage, but their values are clear and necessary for the component. This can be plain data publicly accessible by other classes like function coefficients, trajectory samples or training data. Those properties are not kept track of, but enabling to register them within the surveillance system avoids messages that they are candidates for monitoring but have not been registered.
Experimental Experimental properties are settings whose effect on simulations have not been investigated completely or that might soon disappear. Properties of this level should not appear in production software, and any result produced with experimental properties should be questioned.

Note: This program makes use of the cprintf-function (File-Exchange #24093), if available. This way a more expressive colored summary can be printed. If not present, the standard output and error output streams (FileIDs 1 & 2) are used.

Author: Daniel Wirtz

Date: 2011-11-18

Todo:

Check if it makes sense to "link" properties with other known properties that helps to emphasize dependencies. maybe even a callback that validates a connected pair?
include a disable propchange listening flag for use during simulations.
maybe move the Text and Short property extractions to the getDPCMReport method? -> speedup
include DefaultConfirmed flag into output!

Redistribution and use in source and binary forms, with or without modification, are permitted only in compliance with the BSD license, see http://www.opensource.org/licenses/bsd-license.php

This class collection allows to automatically supervise changes to properties' default settings and create reports of different detail and level for them.

The purpose of this tool is to improve the reliability and quality of small software tools or even frameworks by ensuring that any end-users of the software get appropriate warnings when NOT changing default values, whose values have been chosen to the best knowledge of the programmers/developers but still might be critical or of great importance for the outcome of the computation.

Target group is any MatLab programmer who develops classes and functionalities (e.g. simulation- or discretization tools, solvers etc) that are used by different people who might lack the domain knowledge of the program at hand.

Roughly, the idea is to register any publicly changeable property after setting the default values and process any changes made to the properties at a later stage (by using the SetObservable flag for MatLab classes)

Example: Create a DPCMDemoClass instance and run the demo! dc = DPCMDemoClass; dc.demo; % Watch out, there are pauses included! :-)

The monitoring system distinguishes between several classes of properties that allow for a more precise categorization.

DPCM property classes

Critical A critical property is vital for the algorithm performance and result. This might be a given accuracy level or the consistency order for a discretization scheme. Any critical properties should have been set or at least validated by the end-user before simulations are started, otherwise a well-noticeable warning is issued.
Important Important properties are next in the order after the critical level. The difference is that those properties have an influence on the overall result, but will not lead to a totally different quality of the algorithm result. This might be an explicit jacobian matrix which would otherwise be computed by finite differences, a number of different samples to take or the simulation end time which is of course important for the computational time needed but does not affect the simulation quality. If any important properties have not been changed from their default value, a notice appears before the simulation.
alglimit Algorithm limit properties are of fail-safe nature. Sometimes algorithms have stopping conditions that are checked for within iterations which usually stop when some prescribed accuracy is gained. However, if an algorithm does not reach such states a maximum number of iterations can be put in place to force abortion of the iterations. As those properties are supposed to have appropriate (=high enough) default values simulations can be started without changing them. However, presence of those properties almost always implies the presence of a critical property like an accuracy level which is the first algorithm stopping condition.
scaling Scaling properties are used to perform numerical scaling of time, space or states within a numerical simulation. They are of an optional nature and thus are not elemental for simulations to produce accuracte results. However, for this special level it might very well be important if some scaling properties are set and some others are not. This might lead to wrong computational results and thus a warning is issued if not all or none of those properties are changed.
optional Optional properties are, well, optional. They can refer to whole components of a simulation that can be plugged in or not, specify a custom behaviour which will otherwise be computed in a correct but possibly more ineffective way or simply set the name of a component.
data Data properties circumfence all properties that must be set (or even will be set by the framework) at some stage, but their values are clear and necessary for the component. This can be plain data publicly accessible by other classes like function coefficients, trajectory samples or training data. Those properties are not kept track of, but enabling to register them within the surveillance system avoids messages that they are candidates for monitoring but have not been registered.
Experimental Experimental properties are settings whose effect on simulations have not been investigated completely or that might soon disappear. Properties of this level should not appear in production software, and any result produced with experimental properties should be questioned.

Note: This program makes use of the cprintf-function (File-Exchange #24093), if available. This way a more expressive colored summary can be printed. If not present, the standard output and error output streams (FileIDs 1 & 2) are used.

Author: Daniel Wirtz

Date: 2011-11-18

Todo:

Check if it makes sense to "link" properties with other known properties that helps to emphasize dependencies. maybe even a callback that validates a connected pair?
include a disable propchange listening flag for use during simulations.
maybe move the Text and Short property extractions to the getDPCMReport method? -> speedup
include DefaultConfirmed flag into output!

Redistribution and use in source and binary forms, with or without modification, are permitted only in compliance with the BSD license, see http://www.opensource.org/licenses/bsd-license.php

Definition at line 17 of file DPCM.m.

Static Public Member Functions
static function	getDPCMReport (DPCMobj, levels)
	Prints a detailed report about the properties at each level which have not been changed from their default setting. More...

static function	getDPCMSummary (DPCMobj, levels)
	Prints a summary about the properties of different levels which have not been changed from their default setting. More...

static function	criticalsCheck (DPCMobj)
	This is a shorthand method that runs the DPCM but only for critical properties. More...

static function	getDPCMReport (DPCMobj, levels)

static function	getDPCMSummary (DPCMobj, levels)

static function	criticalsCheck (DPCMobj)

Static Public Attributes
static const ::cell	PropClasses = {"'critical','important','alglimit','scaling','optional','data','experimental','verbose'"}
	The known property classes. More...

static const ::char	PropClassesLink = "matlab:help DPCM"
	Change this value to a more expressive one, i.e. a link to your software documentation which includes the DPCM part. More...

Member Function Documentation

function DPCM.criticalsCheck ( DPCMobj )

static

This is a shorthand method that runs the DPCM but only for critical properties.

Use this method e.g. in front of your higher-level simulate/solve/etc methods.

Required fields of DPCMobj:

Definition at line 192 of file DPCM.m.

References PropClasses.

Referenced by models.BaseFullModel.computeTrajectory(), and DPCMDemoClass.doSomeComputation().

Here is the caller graph for this function:

static function DPCM.criticalsCheck ( DPCMobj )

static

Definition at line 192 of file DPCM.m.

References PropClasses.

static function DPCM.getDPCMReport	(	DPCMobj,
		levels
	)

static

Definition at line 143 of file DPCM.m.

References PropClasses.

function DPCM.getDPCMReport	(	DPCMobj,
		levels
	)

static

Prints a detailed report about the properties at each level which have not been changed from their default setting.

Call this method after any calls to models.BaseModel.simulate or models.BaseModel.getTrajectory

See Also: getDPCMSummary criticalsCheck

Parameters

DPCMobj	The object to get the report for.
levels	[Optional] The property levels to print reports for. A list of admissible values can be obtained by DPCM.PropClasses. Default is to print 'all' data.

Definition at line 143 of file DPCM.m.

References PropClasses.

Referenced by DPCMDemoClass.doSomeComputation().

Here is the caller graph for this function:

function DPCM.getDPCMSummary	(	DPCMobj,
		levels
	)

static

Prints a summary about the properties of different levels which have not been changed from their default setting.

See Also: getDPCMReport criticalsCheck

Parameters

DPCMobj	The object to get the summary for.
levels	[Optional] The property levels to print reports for. A list of admissible values can be obtained by DPCM.PropClasses. Default is to print 'all' data.

Definition at line 169 of file DPCM.m.

References PropClasses.

Referenced by DPCMDemoClass.doSomeComputation().

Here is the caller graph for this function:

static function DPCM.getDPCMSummary	(	DPCMobj,
		levels
	)

static

Definition at line 169 of file DPCM.m.

References PropClasses.

Member Data Documentation

DPCM.PropClasses = {"'critical','important','alglimit','scaling','optional','data','experimental','verbose'"}

static

The known property classes.

Extend them at your need, however, the only restriction is to leave "critical" as first entry.

Default: {"'critical','important','alglimit','scaling','optional','data','experimental','verbose'"}

Definition at line 114 of file DPCM.m.

Referenced by criticalsCheck(), getDPCMReport(), getDPCMSummary(), and DPCMObject.registerProps().

DPCM.PropClassesLink = "matlab:help DPCM"

static

Change this value to a more expressive one, i.e. a link to your software documentation which includes the DPCM part.

Default: "matlab:help DPCM"

Definition at line 128 of file DPCM.m.

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

dpcm/DPCM.m

Detailed Description

Static Public Member Functions

Static Public Attributes

Member Function Documentation

Member Data Documentation