#include <ImFusion/Base/Optimizer.h>

Non-linear optimization. More...

Inheritance diagram for Optimizer:

Detailed Description

Non-linear optimization.

In a derived class, the actual optimization routine has to be implemented. This class however provides all the tools needed for executing and evaluating the performance of non-linear optimization algorithms, including randomized studies and grid plots.

Public Types
enum	Mode { OPT = 0 , STUDY = 1 , PLOT = 2 , EVALUATE = 3 }
	Mode of operation when execute is called. More...

Public Member Functions
	Optimizer (int n, int type, CostFunction *cf=0, const std::vector< std::string > &paramNames={})
	Constructor with dimension and optimization type.

	~Optimizer () override
	Destructor.

virtual void	setType (int val)
	Set the optimizer type.

void	setCostFunction (CostFunction *cf)
	Set the cost function.

void	setErrorFunction (ErrorFunction *ef)
	Set an optional error function.

void	setProgress (Progress *p)
	Provide an optional progress callback.

void	setProgressUpdate (bool flag)
	Specify if a progress update shall be shown during optimization (does not apply for randomized studies)

bool	progressUpdate () const

void	setProgressBetter (bool flag)
	Specify if progress update should only be called if cost function has improved.

bool	progressBetter () const

void	setProgressUpdatesDisplay (bool flag)
	Specify if whether the Optimizer should set the Update Display flag when reporting progress.

bool	progressUpdatesDisplay () const

void	setProgressText (const std::string &description)
	Specify optional custom description for progress reporting (ignored if empty)

const std::string &	progressText () const

std::string	paramName (int i) const
	Get the name of a parameter if it has been specified, otherwise defaults to "Parameter i".

void	setParamNames (const std::vector< std::string > &paramNames)
	Set the names of the parameters.

bool	hasParamNames () const
	True, if m_paraNames is not empty.

void	setLogging (int file, int console=0)
	Set level of detail for logging to both text file and the console.

std::pair< int, int >	logging () const

void	setLogFilename (const std::string &filename)
	Set a custom log file name or path (file logging has to be enabled/disabled independently with setLogging)

void	setAddToStudy (bool flag)
	Specify whether individual optimization runs should be added to the OptimizationStudy.

void	repeatSelection (int n, int extra=0)
	Reconfigures the optimizer to solve a problem with the size of n times the selection.

void	setMinimize (bool flag)
	Specify if the cost function is to be minimized or maximized.

void	setScale (double scale)
	Set an overall parameter scaling.

void	setScale (const std::vector< double > scale)
	Set an individual parameter scaling.

void	setSelection (const std::vector< bool > &sel)
	Specify that only some of the parameters should be optimized.

void	setMode (Mode mode, double range=1.0, int steps=1, bool includeOrig=false)
	Set the desired mode of operation, as well as range and steps for study or plot.

virtual int	execute (double *x)
	Execute the optimization given initial parameters of full dimensionality. Negative return values indicate an error.

double	evaluate (int n, const double x, double dx=0) override
	Wraps the cost function evaluation.

void	shrink (const double all, double sel) const
	Shrink to selected parameters and/or divide by scaling.

void	expand (const double sel, double all) const
	Expand to all parameters and/or multiply by scaling.

Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.

void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().

void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.

	Configurable (const Configurable &rhs)

	Configurable (Configurable &&rhs) noexcept

Configurable &	operator= (const Configurable &)

Configurable &	operator= (Configurable &&) noexcept

Public Attributes
Signal< int, int >	signalStudyStepFinished
	Signal emitted after each step of a random study, arguments are <current step> and <num total steps>

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Protected Member Functions
virtual int	run (double *x)=0
	Run a single optimization with selected parameters. Negative return values indicate an error.

virtual const char *	resultName (int value) const
	Return a string describing the optimizer's return value.

void	computeStats (double *pars, int n) const
	Compute statistics on random study parameters.

void	randomOptimization (double *pars)
	Executes successive optimizations with randomized initial parameters.

void	computePlot (double *pars)
	Computes a 1D or 2D plot of selected parameters.

virtual int	percentageDone (const double *curPars)
	Computes an approximation of how close we are to the abortion criteria.

void	logResultFile (const double pInit, const double pOpt)
	Auxiliary method to write the optimization result to a file.

void	logResultConsole (const double *pOpt, int result=0)
	Auxiliary method to log the optimization result to the console.

Protected Attributes
CostFunction *	m_cf = nullptr
	Cost function instance to be optimized.

ErrorFunction *	m_ef = nullptr
	Optional error function instance.

Progress *	m_progress = nullptr
	Optional progress callback.

std::unique_ptr< Progress::Task >	m_progressTask
	progress reporting instance of execute()

std::unique_ptr< Timer >	m_timer
	Timer instance.

std::unique_ptr< OptimizationStudy >	m_study
	Results of random study.

bool	m_addToStudy = false
	Optimization study is automatically appended.

Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Configuration
int	m_dim
	Dimensions of the optimization problem.

int	m_selDim
	Dimensions of the selected parameters.

int	m_type
	Implementation-specific optimization type.

int	m_loggingF = 0
	Level of detail for file logging.

int	m_loggingC = 0
	Level of detail for console logging.

int	m_abortEval = 0
	Maximum number of cost function evaluations.

double	m_abortTime = 0.0
	Number of seconds after which to abort.

double	m_abortFunVal = 0.0
	Abort when this function values is reached.

double	m_abortFunTol = 0.0
	Cost function tolerance abortion criteria.

double	m_abortParTol = 0.0
	Parameter tolerance abortion criteria.

bool	m_minimize = false
	Shall the cost function be minimized or maximized.

bool	m_updateProgress = true
	Progress updates won't be called unless this is true.

bool	m_updateBetter = false
	Update progress only if cost function has improved.

bool	m_progressUpdateDisplay = false
	Flag whether the Optimizer should set the Update Display flag when reporting progress.

std::string	m_progressText
	Optional custom description to use for progress reporting.

bool	m_studyOrig = false
	If true, random study includes original parameters.

Mode	m_mode = OPT
	Mode of operation (optimization, study or plot)

double	m_range = 1.0
	Range for random study or plot.

int	m_steps = 1
	Number of steps for random study or plot.

std::vector< double >	m_lowerBounds
	Lower bounds for bound-constrained optimization.

std::vector< double >	m_upperBounds
	Upper bounds for bound-constrained optimization.

std::vector< double >	m_scale
	Parameter scaling (i.e. step sizes)

std::vector< bool >	m_sel
	Parameter selection for optimization.

std::vector< std::string >	m_paramNames
	Names of each parameter.

Working variables
bool	m_first = true
	Is this the first cost function evaluation.

bool	m_auxPars = false
	Are auxiliary parameters in use.

std::atomic< bool >	m_aborted {false}
	Optimizer was aborted.

int	m_run = 0
	Current run (for repeated optimization)

int	m_eval = 0
	Actual number of cost function evaluations.

double	m_time = 0.0
	Execution time of the optimizer.

double	m_firstVal = 0.0
	First cost function value.

double	m_bestVal = 0.0
	Best cost function value so far.

double	m_doneEst = 0.0
	Estimation of completeness.

std::vector< double >	m_lastPars
	Last parameter vector for assessing completeness.

std::vector< double >	m_firstError
	First values of optional errors.

std::vector< double >	m_error
	Current values of optional errors.

double *	m_pars = nullptr
	The original parameter vector.

std::vector< double >	m_parGradients

std::string	m_logFilename
	Custom log file name or path.

std::ofstream	m_logFile
	The log file.

float *	m_plotData = nullptr
	Plot result data.

Abortion criteria, at least one of those should be set
void	setAbortEval (int num)

int	abortEval () const

void	setAbortTime (double sec)
	Abort after a certain elapsed number of seconds.

double	abortTime () const

void	setAbortFunVal (double val)
	Abort if this function value is reached.

double	abortFunVal () const

void	setAbortFunTol (double val)
	Abort if change in cost function value is becomes too small.

double	abortFunTol () const

void	setAbortParTol (double val)
	Abort if change in parameter values becomes too small.

double	abortParTol () const

Different convenience methods to specify a linear bound constraint
void	setBounds (double bounds)
	A value of zero disables the bounds.

void	setBounds (double lower, double upper)
	Set the same lower and upper bounds for all parameters.

void	setBounds (const std::vector< double > &bounds)
	Set individual symmetric bounds.

void	setBounds (const std::vector< double > &lower, const std::vector< double > &upper)
	Set individual lower and upper bounds.

const std::vector< double > &	lowerBounds () const

const std::vector< double > &	upperBounds () const

Query some information
int	type () const

Mode	mode () const
	Return the mode of operation.

bool	minimize () const
	Return whether cost function is minimized.

double	range () const
	Return range for study or plot.

int	steps () const
	Return the number of steps for used for study or plot.

bool	studyIncludeOrig () const
	Return whether random studies shall include the original parameters.

double	firstVal () const
	Return cost function value of first evaluation.

double	bestVal () const
	Return best cost function value.

double	error (int which=0) const
	Return current value of error function.

int	numEval () const
	Return number of executed cost function evaluations.

bool	isAtBounds (std::vector< int > *indicesAtBounds=nullptr) const
	Return whether the current parameters touch the specified bounds, and their indices if a vector is passed.

int	dimension () const
	Return the total number of parameters (dimension)

void	setDimension (int d)
	Sets the dimension and the number of selected parameters to `d` and clears the selection.

int	selDim () const
	Return number of selected parameters.

const std::vector< bool > &	selection () const
	Return the selected parameters.

const std::vector< double > &	scale () const
	Return the parameter scaling.

Progress *	progress ()
	Return the progress callback.

ErrorFunction *	errorFunction ()
	Return the error function pointer.

virtual void	abort ()=0
	Request to abort the optimization.

bool	aborted () const
	Return if the optimizer was aborted.

float *	plotData ()
	Return plot result data.

OptimizationStudy *	studyResults () const
	Return random study result. Do not delete returned Optimization study object. It is owned by the Optimization class.

bool	addToStudy () const
	Return whether optimization runs are added to the study.

const std::string &	logFilename () const
	Return the custom log file name.

Implements the Configurable interface
void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.

void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.

Member Enumeration Documentation

◆ Mode

enum Mode

Mode of operation when execute is called.

Enumerator
OPT	Single optimization.
STUDY	Randomized study.
PLOT	1D or 2D plot
EVALUATE	Single cost function evaluation.

Member Function Documentation

◆ setType()

virtual void setType ( int val )

virtual

Set the optimizer type.

Reimplemented in OptimizerNL.

◆ setLogging()

void setLogging	(	int	file,
		int	console = 0 )

inline

Set level of detail for logging to both text file and the console.

0 = none (default), 1 = init/result, 2 = every evaluation, 3 = only final result after study

◆ repeatSelection()

void repeatSelection	(	int	n,
		int	extra = 0 )

Reconfigures the optimizer to solve a problem with the size of n times the selection.

Optionally, an extra number of parameters is appended at the end once. This method changes the dimensionality of the optimizer and clears the selection.

◆ setAbortEval()

void setAbortEval ( int num )

inline

Abort after a certain number of cost function evaluations

◆ setBounds()

void setBounds ( double bounds )

A value of zero disables the bounds.

Set the same symmetric bounds in all parameters

◆ setMode()

void setMode	(	Mode	mode,
		double	range = 1.0,
		int	steps = 1,
		bool	includeOrig = false )

Set the desired mode of operation, as well as range and steps for study or plot.

The last flag denotes whether the original parameters shall be included in a random study.

◆ execute()

virtual int execute ( double * x )

virtual

Execute the optimization given initial parameters of full dimensionality. Negative return values indicate an error.

Reimplemented in OptimizerSeries.

◆ evaluate()

double evaluate	(	int	n,
		const double *	x,
		double *	dx = 0 )

overridevirtual

Wraps the cost function evaluation.

Implements CostFunction.

◆ type()

int type ( ) const

inline

Return the optimizer type

◆ abort()

virtual void abort ( )

pure virtual

Request to abort the optimization.

Implemented in OptimizerBFGS, OptimizerDiRect, OptimizerNelderMead, OptimizerNL, OptimizerReload, OptimizerSeries, and OptimizerXNES.

◆ configure()

void configure ( const Properties * p )

overridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configuration() for the inverse functionality

Reimplemented from Configurable.

Reimplemented in OptimizerDiRect, OptimizerNelderMead, OptimizerNL, OptimizerSeries, and OptimizerXNES.

◆ configuration()

void configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from Configurable.

Reimplemented in OptimizerDiRect, OptimizerNelderMead, OptimizerNL, OptimizerSeries, and OptimizerXNES.

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

ImFusion/Base/Optimizer.h

Detailed Description

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Configuration

Working variables

Abortion criteria, at least one of those should be set

Different convenience methods to specify a linear bound constraint

Query some information

Implements the Configurable interface

Member Enumeration Documentation

◆ Mode

Member Function Documentation

◆ setType()

◆ setLogging()

◆ repeatSelection()

◆ setAbortEval()

◆ setBounds()

◆ setMode()

◆ execute()

◆ evaluate()

◆ type()

◆ abort()

◆ configure()

◆ configuration()