A description of a non-linear optimisation problem. More...

#include <optimisation.hpp>

Public Types
enum	Method { METHOD_INVALID = CMZN_OPTIMISATION_METHOD_INVALID, METHOD_QUASI_NEWTON = CMZN_OPTIMISATION_METHOD_QUASI_NEWTON, METHOD_LEAST_SQUARES_QUASI_NEWTON = CMZN_OPTIMISATION_METHOD_LEAST_SQUARES_QUASI_NEWTON }

enum	Attribute { ATTRIBUTE_FUNCTION_TOLERANCE = CMZN_OPTIMISATION_ATTRIBUTE_FUNCTION_TOLERANCE, ATTRIBUTE_GRADIENT_TOLERANCE = CMZN_OPTIMISATION_ATTRIBUTE_GRADIENT_TOLERANCE, ATTRIBUTE_STEP_TOLERANCE = CMZN_OPTIMISATION_ATTRIBUTE_STEP_TOLERANCE, ATTRIBUTE_MAXIMUM_ITERATIONS = CMZN_OPTIMISATION_ATTRIBUTE_MAXIMUM_ITERATIONS, ATTRIBUTE_MAXIMUM_FUNCTION_EVALUATIONS = CMZN_OPTIMISATION_ATTRIBUTE_MAXIMUM_FUNCTION_EVALUATIONS, ATTRIBUTE_MAXIMUM_STEP = CMZN_OPTIMISATION_ATTRIBUTE_MAXIMUM_STEP, ATTRIBUTE_MINIMUM_STEP = CMZN_OPTIMISATION_ATTRIBUTE_MINIMUM_STEP, ATTRIBUTE_LINESEARCH_TOLERANCE = CMZN_OPTIMISATION_ATTRIBUTE_LINESEARCH_TOLERANCE, ATTRIBUTE_MAXIMUM_BACKTRACK_ITERATIONS = CMZN_OPTIMISATION_ATTRIBUTE_MAXIMUM_BACKTRACK_ITERATIONS, ATTRIBUTE_TRUST_REGION_SIZE = CMZN_OPTIMISATION_ATTRIBUTE_TRUST_REGION_SIZE }

Public Member Functions
	Optimisation (cmzn_optimisation_id in_optimisation_id)

	Optimisation (const Optimisation &optimisation)

Optimisation &	operator= (const Optimisation &optimisation)

bool	isValid () const

cmzn_optimisation_id	getId () const

Field	getConditionalField (const Field &independentField)

int	setConditionalField (const Field &independentField, const Field &conditionalField)

int	addFieldassignment (const Fieldassignment &fieldassignment)

Method	getMethod ()

int	setMethod (Method method)

int	getAttributeInteger (Attribute attribute)

int	setAttributeInteger (Attribute attribute, int value)

double	getAttributeReal (Attribute attribute)

int	setAttributeReal (Attribute attribute, double value)

Field	getFirstIndependentField ()

Field	getNextIndependentField (const Field &refField)

int	addIndependentField (const Field &field)

int	removeIndependentField (const Field &field)

Field	getFirstObjectiveField ()

Field	getNextObjectiveField (const Field &refField)

int	addObjectiveField (const Field &field)

int	removeObjectiveField (const Field &field)

char *	getSolutionReport ()

int	optimise ()

Protected Attributes
cmzn_optimisation_id	id

Detailed Description

A description of a non-linear optimisation problem.

A description of a non-linear optimisation problem, consisting of the objective fields (generally spatial sums or sum of squares) to be minimised, independent fields whose parameters are to be modified in the optimisation, the solution method and attributes controlling it.

Member Enumeration Documentation

enum OpenCMISS::Zinc::Optimisation::Attribute

Labels of optimisation attributes which may be set or obtained using generic get/set_attribute functions.

Enumerator
ATTRIBUTE_FUNCTION_TOLERANCE	(Opt++ stopping tolerance) Assigns a stopping tolerance for an optimisation algorithm. Please assign tolerances that make sense given the accuracy of your function. For example, setting TOLERANCE to 1.e-4 in your problem means the optimisation algorithm converges when the function value from one iteration to the next changes by 1.e-4 or less. Default value: 1.49012e-8
ATTRIBUTE_GRADIENT_TOLERANCE	(Opt++ stopping tolerance) Assigns a stopping tolerance for an optimisation algorithm. Please assign tolerances that make sense given your function accuracy. For example, setting GRADIENT_TOLERANCE to 1.e-6 in your problem means the optimisation algorithm converges when the absolute or relative norm of the gradient is 1.e-6 or less. Default value: 6.05545e-6
ATTRIBUTE_STEP_TOLERANCE	(Opt++ stopping tolerance) Assigns a stopping tolerance for the optimisation algorithm. Please set tolerances that make sense, given the accuracy of your function. For example, setting STEP_TOLERANCE to 1.e-2 in your problem means the optimisation algorithm converges when the relative steplength is 1.e-2 or less. Default value: 1.49012e-8
ATTRIBUTE_MAXIMUM_ITERATIONS	(Opt++ stopping tolerance) Places a limit on the number of iterations of the optimisation algorithm. It is useful when your function is computationally expensive or you are debugging the optimisation algorithm. When MAXIMUM_ITERATIONS iterations evaluations have been completed, the optimisation algorithm will stop and report the solution it has reached at that point. It may not be the optimal solution, but it will be the best it could provide given the limit on the number of iterations. Default value: 100.
ATTRIBUTE_MAXIMUM_FUNCTION_EVALUATIONS	(Opt++ stopping tolerance) Places an upper bound on the number of function evaluations. The method is useful when your function is computationally expensive and you only have time to perform a limited number of evaluations. When MAXIMUM_NUMBER_FUNCTION_EVALUATIONS function evaluations have been completed, the optimisation algorithm will stop and report the solution it has reached at that point. It may not be the optimal solution, but it will be the best it could provide given the limit on the number of function evaluations. Default value: 1000
ATTRIBUTE_MAXIMUM_STEP	(Opt++ steplength control) Places an upper bound on the length of the step that can be taken at each iteration of the optimisation algorithm. If the scale of your optimisation parameters exceeds the bound, adjust accordingly. If you want to be conservative in your search, you may want to set MAXIMUM_STEP to a smaller value than the default. In our (Opt++) experience, the default value is generally fine. Default value: 1.0e3
ATTRIBUTE_MINIMUM_STEP	(Opt++ steplength control) Places a lower bound on the length of the step that can be taken at each iteration of the optimisation algorithm. If the scale of your optimisation parameters exceeds the bound, adjust accordingly. If you expect the optimisation algorithm to navigate some tricky areas, set MINIMUM_STEP to a smaller value than the default. In our (Opt++) experience, the default value is generally fine. Default value: 1.49012e-8
ATTRIBUTE_LINESEARCH_TOLERANCE	(Opt++ globalisation strategy parameter) In practice, the linesearch tolerance is set to a small value, so that almost any decrease in the function value results in an acceptable step. Suggested values are 1.e-4 for Newton methods and 1.e-1 for more exact line searches. Default value: 1.e-4
ATTRIBUTE_MAXIMUM_BACKTRACK_ITERATIONS	(Opt++ globalisation strategy parameter) Only relevant when you use a algorithm with a linesearch search strategy. The value places a limit on the number of iterations in the linesearch routine of the optimisation algorithm. If the limit is reached before computing a step with acceptable decrease, the algorithm terminates with an error message. The reported solution is not optimal, but the best one given the number of linesearch iterations. Increasing the number of linesearch iterations may lead to an acceptable step, but it also results in more function evaluations and a shorter steplength. Default value: 5
ATTRIBUTE_TRUST_REGION_SIZE	(Opt++ globalisation strategy parameter) Only relevant when you are using an algorithm with a trust-region or a trustpds search strategy. The value initialises the size of the trust region. Default value: 0.1?? ( Todo: Need to better initialise the default value, see https://software.sandia.gov/opt++/opt++2.4_doc/html/ControlParameters.html) If your problem is quadratic or close to it, you may want to initialise the size of the trust region to a larger value. Todo: Reserving this one for when trust region methods are available via the API. Currently everything uses linesearch methods only.

enum OpenCMISS::Zinc::Optimisation::Method

The optimisation methods available via the optimisation object.

Todo:: Might be worth separating the non-linear problem setup from the optimisation algorithm to mirror the underlying Opt++ structure?

Enumerator
METHOD_INVALID	Invalid or unspecified optimisation method.
METHOD_QUASI_NEWTON	The default optimisation method. Suitable for most problems with a small set of independent parameters. Given a scalar valued objective function (scalar sum of all objective fields' components), finds the set of DOFs for the independent field(s) which minimises the objective function value.
METHOD_LEAST_SQUARES_QUASI_NEWTON	A least squares method better suited to larger problems. Finds the set of independent field(s) DOF values which minimises the squares of the objective components supplied. Works specially with fields giving sum-of-squares e.g. nodeset_sum_squares, nodeset_mean_squares to supply individual terms before squaring to the optimiser.

Member Function Documentation

int OpenCMISS::Zinc::Optimisation::addFieldassignment ( const Fieldassignment & fieldassignment )

inline

Add a field assignment object to the optimisation, to be applied before objective evaluation with each set of trial dependent field DOFs, and at the end of optimisation. Multiple field assignments are applied in the order they are added. The main use is to partially apply the effect of the dependent field on the DOFs of another field; an example is optimising a constant offset over a subset of nodes, where DOFs at those nodes contribute to the objective. Note if the source field of the assignment is a function of the target field then target DOFs will drift away. In some cases this is solved by making the source field a function of a copy of the target field with its DOFs prior to the optimise call. However to assign multiple versions and derivatives in the target field requires the source field to be a function of it; the solution is to add two field assignments, the first resets target DOFs to their initial values, the second assigns them to the source values.

Parameters

fieldassignment Field assignment to apply. Must be for a field in the same fieldmodule as this optimisation object.

Returns: Result OK if field successfully added, any other value if failed or already added.

int OpenCMISS::Zinc::Optimisation::addIndependentField ( const Field & field )

inline

Add an independent field to the given optimisation problem description. Valid independent fields are limited to constant and finite_element types. The parameters of these fields are modified to minimise the objective fields. NOTE: Beware that many existing cubic Hermite meshes in EX format do not correctly share common value or derivative versions and thus will 'open up' during fitting/optimisation.

Parameters

field Real-valued independent field to add to the optimisation object (accessed internally so safe for caller to destroy locally).

Returns: Status OpenCMISS::Zinc::OK if field successfully added, any other value if failed or already added.

int OpenCMISS::Zinc::Optimisation::addObjectiveField ( const Field & field )

inline

Add an objective field to the optimisation problem description. Valid objective fields must be spatially constant. The least squares solution method treats fields performing a sum of squares (nodeset_sum_squares, nodeset_mean_squares) specially, passing each term to the optimiser. The overall objective function becomes the sum of all components of all objective fields, or for the least-squares method, the sum of the squares of all terms (or components if the objective field is not a sum of squares).

Parameters

field Real-valued objective field to add to the optimisation object (accessed internally so safe for caller to destroy locally).

Returns: Status OpenCMISS::Zinc::OK if field successfully added, any other value if failed or already added.

int OpenCMISS::Zinc::Optimisation::getAttributeInteger ( Attribute attribute )

inline

Get an integer or Boolean attribute of the optimisation object.

Parameters

attribute The identifier of the integer attribute to get.

Returns: Value of the attribute. Boolean values are 1 if true, 0 if false.

double OpenCMISS::Zinc::Optimisation::getAttributeReal ( Attribute attribute )

inline

Get a real attribute of the optimisation object.

Parameters

attribute The identifier of the real attribute to get.

Returns: Value of the attribute.

Field OpenCMISS::Zinc::Optimisation::getConditionalField ( const Field & independentField )

inline

Get the conditional field which controls which degrees of freedom of an independent field are included in the optimisation, if any.

See also: Optimisation::setConditionalField

Parameters

independentField The independent field the condition applies to.

Returns: Handle to conditional field, or NULL/invalid handle if none or failed.

Field OpenCMISS::Zinc::Optimisation::getFirstIndependentField ( )

inline

Get the first independent field from the optimisation problem description.

See also: Optimisation::getNextIndependentField

Returns: Handle to first independent field, or NULL/invalid handle if none or failed.

Field OpenCMISS::Zinc::Optimisation::getFirstObjectiveField ( )

inline

Get the first objective field from the optimisation problem description.

See also: Optimisation::getNextObjectiveField

Returns: Handle to first objective field, or NULL/invalid handle if none or failed.

cmzn_optimisation_id OpenCMISS::Zinc::Optimisation::getId ( ) const

inline

Return the C handle of the Optimisation object.

Returns: C handle of Optimisation if this objects is valid, 0 otherwise.

Method OpenCMISS::Zinc::Optimisation::getMethod ( )

inline

Get the current optimisation method for the given optimisation object.

Returns: The current optimisation method.

Field OpenCMISS::Zinc::Optimisation::getNextIndependentField ( const Field & refField )

inline

Get the next independent field in the optimisation problem description after the supplied ref_field. Use to iterate over the independent fields, taking care to destroy all returned field handles exactly once:

cmzn_field_id field = cmzn_optimisation_get_first_objective_field(optimisation); while (field) { cmzn_field_id next_field = cmzn_optimisation_get_next_objective_field(optimisation, field); cmzn_field_destroy(&field); field = next_field; }

Parameters

refField Handle to an independent field from the optimisation.

Returns: Handle to next independent field after ref_field, or NULL/invalid handle if none or failed.

Field OpenCMISS::Zinc::Optimisation::getNextObjectiveField ( const Field & refField )

inline

Get the next objective field in the optimisation problem description after the supplied ref_field. Use to iterate over the objective fields, taking care to destroy all returned field handles exactly once:

cmzn_field_id field = cmzn_optimisation_get_first_objective_field(optimisation); while (field) { cmzn_field_id next_field = cmzn_optimisation_get_next_objective_field(optimisation, field); cmzn_field_destroy(&field); field = next_field; }

Parameters

refField Handle to an objective field from the optimisation.

Returns: Handle to next objective field after ref_field, or NULL/invalid handle if none or failed.

char* OpenCMISS::Zinc::Optimisation::getSolutionReport ( )

inline

Get a textual report on the last solution.

Returns: Allocated string containing report which user must free using cmzn_deallocate, or NULL on error or if haven't performed optimisation yet.

bool OpenCMISS::Zinc::Optimisation::isValid ( ) const

inline

Check if this is a valid Optimisation object.

Returns: Status True if object is valid, false otherwise.

int OpenCMISS::Zinc::Optimisation::optimise ( )

inline

Perform the optimisation described by the provided optimisation object.

Returns: Status OpenCMISS::Zinc::OK if optimisation completed successfully (stopping criteria satisfied), and any other value on failure.

int OpenCMISS::Zinc::Optimisation::removeIndependentField ( const Field & field )

inline

Remove an independent field from the optimisation problem.

Parameters

field The independent field to remove.

Returns: Status OpenCMISS::Zinc::OK if field successfully removed, any other value if failed or field not found.

int OpenCMISS::Zinc::Optimisation::removeObjectiveField ( const Field & field )

inline

Remove an objective field from the optimisation problem.

Parameters

field The objective field to remove.

Returns: Status OpenCMISS::Zinc::OK if field successfully removed, any other value if failed or field not found.

int OpenCMISS::Zinc::Optimisation::setAttributeInteger	(	Attribute	attribute,
		int	value
	)

inline

Set an integer or Boolean attribute of the optimisation object.

Parameters

attribute	The identifier of the integer attribute to set.
value	The new value for the attribute. For Boolean values use 1 for true in case more options are added in future.

Returns: Status OpenCMISS::Zinc::OK if attribute successfully set, any other value if failed or attribute not valid or able to be set for this optimisation object.

int OpenCMISS::Zinc::Optimisation::setAttributeReal	(	Attribute	attribute,
		double	value
	)

inline

Set a real attribute of the optimisation object.

Parameters

attribute	The identifier of the real attribute to set.
value	The new value for the attribute.

Returns: Status OpenCMISS::Zinc::OK if attribute successfully set, any other value if failed or attribute not valid or able to be set for this optimisation object.

int OpenCMISS::Zinc::Optimisation::setConditionalField	(	const Field &	independentField,
		const Field &	conditionalField
	)

inline

Set a conditional field which controls which degrees of freedom of an independent field are included in the optimisation, for all components or per-component. The conditional field is queried at the start of the optimisation, so the number of DOFs remains constant throughout it. The conditional field only applies to finite element independent fields, and is queried and applied to nodal DOFs only.

Parameters

independentField	The independent field to select a subset of DOFs from. Must already have been added to the optimisation.
conditionalField	A field with either one component or the same number of components as the independent field. DOFs for the independent field (or components of it, if non-scalar) are included only where this field is defined and non-zero. Pass a NULL/invalid handle to clear.

Returns: Status OpenCMISS::Zinc::OK on success, any other value on failure.

int OpenCMISS::Zinc::Optimisation::setMethod ( Method method )

inline

Set the optimisation method for the given optimisation object.

Parameters

method The optimisation method to use.

Returns: Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.

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

auto_comments_output/optimisation.hpp

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation