#include <mango.hpp>

Inheritance diagram for mango::Problem:

Public Member Functions
	Problem (int N_parameters, double state_vector, objective_function_type objective_function, int argc, char *argv)
	Constructor for a standard optimization problem. More...

	~Problem ()
	Destructor. More...

void	mpi_init (MPI_Comm mpi_comm)
	Initialize MANGO's internal MPI data that describes the partitioning of the processes into worker groups. More...

void	set_algorithm (algorithm_type algorithm)
	Sets the optimization algorithm. More...

void	set_algorithm (std::string algorithm_str)
	Sets the optimization algorithm. More...

void	read_input_file (std::string filename)
	Reads in the number of worker groups and algorithm from a file. More...

void	set_output_filename (std::string filename)
	Sets the name of the output file that will record values of the objective function at each evaluation. More...

void	set_bound_constraints (double lower, double upper)
	Sets bound constraints for the optimization problem. More...

double	optimize ()
	Solve the optimization problem that has been set up. More...

int	get_N_parameters ()
	Get the number of independent variables for an optimization problem. More...

int	get_best_function_evaluation ()
	For an optimization problem that has already been solved, return the index of the function evaluation corresponding to the optimum. More...

int	get_function_evaluations ()
	For an optimization problem that has already been solved, return the number of times the objective function was evaluated. More...

double *	get_state_vector ()
	Get the vector of independent variables. More...

void	set_centered_differences (bool centered_differences)
	Control whether 1-sided or centered finite differences will be used to compute derivatives of the objective function. More...

void	set_finite_difference_step_size (double finite_difference_step_size)
	Set an absolute step size for finite difference derivatives. More...

void	set_max_function_evaluations (int N)
	Set the maximum number of evaluations of the objective function that will be allowed before the optimization is terminated. More...

void	set_verbose (int verbose)
	Control how much diagnostic information is printed by MANGO. More...

void	set_output_filename (std::string &filename)
	Sets the name of the output file that will record values of the objective function at each evaluation. More...

void	set_user_data (void *user_data)
	Pass the prescribed pointer to the objective function whenever it is called. More...

void	set_relative_bound_constraints (double min_factor, double max_factor, double min_radius, bool preserve_sign)
	Impose bound constraints on an optimization problem, with the bounds chosen as multiples of the initial state vector. More...

void	set_N_line_search (int N_line_search)
	Sets the number of points considered as a set for parallel line searches. More...

Solver *	get_solver ()
	Get the Solver object associated with the optimization problem. More...

Public Attributes
MPI_Partition	mpi_partition

Protected Attributes
Solver *	solver

Friends
class	Solver

Detailed Description

Definition at line 442 of file mango.hpp.

Constructor & Destructor Documentation

◆ Problem()

mango::Problem::Problem	(	int	N_parameters,
		double *	state_vector,
		objective_function_type	objective_function,
		int	argc,
		char **	argv
	)

Constructor for a standard optimization problem.

Parameters

[in]	N_parameters	Number of independent variables.
[in]	state_vector	An array of size N_parameters, giving the initial values of the independent variables.
[in]	objective_function	The objective function to minimize.
[in]	argc	(Optional) A number of arguments. Used to pass options to some optimization libraries.
[in]	argv	(Optional) An array of arguments. Used to pass options to some optimization libraries.

Definition at line 27 of file Problem.cpp.

◆ ~Problem()

mango::Problem::~Problem ( )

Destructor.

Definition at line 37 of file Problem.cpp.

Member Function Documentation

◆ get_best_function_evaluation()

int mango::Problem::get_best_function_evaluation ( )

For an optimization problem that has already been solved, return the index of the function evaluation corresponding to the optimum.

Returns: The index of the function evaluation corresponding to the optimum. If mango::Problem::optimize() has not yet been called, a value of -1 will be returned.

Definition at line 46 of file Problem.cpp.

◆ get_function_evaluations()

int mango::Problem::get_function_evaluations ( )

For an optimization problem that has already been solved, return the number of times the objective function was evaluated.

Returns: The number of times the objective function was evaluated. If mango_optimize has not yet been called, a value of 0 will be returned.

Definition at line 54 of file Problem.cpp.

◆ get_N_parameters()

int mango::Problem::get_N_parameters ( )

Get the number of independent variables for an optimization problem.

Definition at line 42 of file Problem.cpp.

◆ get_solver()

mango::Solver * mango::Problem::get_solver ( )

Get the Solver object associated with the optimization problem.

Users generally should not need this method.

Returns: The Solver object associated with the optimization problem.

Definition at line 180 of file Problem.cpp.

◆ get_state_vector()

double * mango::Problem::get_state_vector ( )

Get the vector of independent variables.

If mango::Problem::optimize() has not yet been called, this vector corresponds to the initial condition. If mango::Problem::optimize() has been called, this vector corresponds to the location of the optimum that was found.

Returns: A pointer to the vector of length N_parameters storing the independent variables.

Definition at line 50 of file Problem.cpp.

◆ mpi_init()

void mango::Problem::mpi_init ( MPI_Comm mpi_comm )

Initialize MANGO's internal MPI data that describes the partitioning of the processes into worker groups.

This subroutine divides up the available MPI processes into worker groups, after checking to see if the selected optimization algorithm supports concurrent function evaluations. Do not confuse this subroutine with MPI_Init, the routine from MPI that initializes MPI itself! mango_mpi_init must be called by the driver code after the call to MPI_Init. This subroutine should be called after setting N_worker_groups and setting the optimization algorithm. This way, MANGO can change N_worker_groups to 1 if an algorithm is chosen that does not support concurrent function evaluations.

Parameters

[in] mpi_comm The MPI communicator to use for the optimization. Usually this is MPI_COMM_WORLD. However, if you want to run the optimization on a subset of MPI_COMM_WORLD, you can supply the appropriate communicator instead.

Definition at line 90 of file Problem.cpp.

◆ optimize()

double mango::Problem::optimize ( )

Solve the optimization problem that has been set up.

This is the main computationally demanding step.

Returns: The minimum value found for the objective function.

Definition at line 119 of file Problem.cpp.

◆ read_input_file()

void mango::Problem::read_input_file ( std::string filename )

Reads in the number of worker groups and algorithm from a file.

This subroutine is used in the examples, so the testing framework can vary the number of worker groups and optimization algorithm.

Parameters

[in] filename The filename of the file to read.

Definition at line 25 of file read_input_file.cpp.

◆ set_algorithm() [1/2]

void mango::Problem::set_algorithm ( algorithm_type algorithm )

Sets the optimization algorithm.

Note the related subroutine of the same name that takes a std::string as input.

Parameters

[in] algorithm One of the enumerated constants representing optimization algorithms. If this supplied integer is too large or too small, a C++ exception will be thrown.

Definition at line 25 of file algorithms.cpp.

◆ set_algorithm() [2/2]

void mango::Problem::set_algorithm ( std::string algorithm_str )

Sets the optimization algorithm.

Note the related subroutine of the same name that takes a mango::algorithm_type as input.

Parameters

[in] algorithm_str A lowercase string containing one of the available algorithms, e.g. "petsc_nm". If the string supplied does not match any of the available algorithms, a C++ exception will be thrown.

Definition at line 36 of file algorithms.cpp.

◆ set_bound_constraints()

void mango::Problem::set_bound_constraints	(	double *	lower,
		double *	upper
	)

Sets bound constraints for the optimization problem.

Parameters

[in]	lower	An array of lower bounds, corresponding to the vector of independent parameters. It is assumed that an array of size N_parameters has been properly allocated.
[in]	upper	An array of upper bounds, corresponding to the vector of independent parameters. It is assumed that an array of size N_parameters has been properly allocated.

Definition at line 58 of file Problem.cpp.

◆ set_centered_differences()

void mango::Problem::set_centered_differences ( bool centered_differences )

Control whether 1-sided or centered finite differences will be used to compute derivatives of the objective function.

Parameters

centered_differences If true, centered differences will be used. If false, 1-sided differences will be used. Centered differences are more accurate, but require more function evaluations (2*N_parameters) compared to 1-sided differences (which require N_parameters+1 evaluations).

Definition at line 64 of file Problem.cpp.

◆ set_finite_difference_step_size()

void mango::Problem::set_finite_difference_step_size ( double finite_difference_step_size )

Set an absolute step size for finite difference derivatives.

Parameters

[in] finite_difference_step_size An absolute step size to use for finite difference derivatives.

Definition at line 68 of file Problem.cpp.

◆ set_max_function_evaluations()

void mango::Problem::set_max_function_evaluations ( int N )

Set the maximum number of evaluations of the objective function that will be allowed before the optimization is terminated.

Parameters

[in] N The maximum number of evaluations of the objective function that will be allowed before the optimization is terminated. If this number is less than 1, a C++ exception will be thrown.

Definition at line 72 of file Problem.cpp.

◆ set_N_line_search()

void mango::Problem::set_N_line_search ( int N_line_search )

Sets the number of points considered as a set for parallel line searches.

The default value is 0. If the value is \(\le 0\), the number will be set to the number of worker groups. Normally this default is the best choice, in terms of load balancing. However you may occasionally wish to set the number of points in a line search to some other value, particularly for tests involving parallelization.

Parameters

N_line_search The number of points considered as a set for parallel line searches.

Definition at line 176 of file Problem.cpp.

◆ set_output_filename() [1/2]

void mango::Problem::set_output_filename ( std::string & filename )

Sets the name of the output file that will record values of the objective function at each evaluation.

Parameters

[in] filename A string giving the filename to use for the output file. If the file already exists, it will be over-written.

◆ set_output_filename() [2/2]

void mango::Problem::set_output_filename ( std::string filename )

Sets the name of the output file that will record values of the objective function at each evaluation.

Parameters

[in] filename A string giving the filename to use for the output file. If the file already exists, it will be over-written.

Definition at line 81 of file Problem.cpp.

◆ set_relative_bound_constraints()

void mango::Problem::set_relative_bound_constraints	(	double	min_factor,
		double	max_factor,
		double	min_radius,
		bool	preserve_sign
	)

Impose bound constraints on an optimization problem, with the bounds chosen as multiples of the initial state vector.

To use this subroutine, you must first call mango::Problem::set_bound_constraints, so MANGO has pointers to the arrays allocted by the user for lower and upper bounds. mango::Problem::set_relative_bound_constraints will overwrite the entries of these arrays.

There are two possible methods of determining the bound constraints using this subroutine, depending on the parameter preserve_sign.

If preserve_sign is false, the bounds will be symmetric about 0, given by the value of the initial condition multiplied by max_factor, expanded to be at least min_radius different from the initial condition. Thus, for independent variable \( x_j \), the bounds will be \( x_j \in [-R_j, R_j] \), where \( R_j = \max(\mathtt{min\_radius}, |x_j| \mathtt{max\_factor})\). Note that the parameter min_factor is not used in this case.

If preserve_sign is true, the lower and upper bounds for a given independent variable will have the same sign as the corresponding element of state_vector (the initial condition supplied to the constructor). The bounds are determined by multiplying each independent variable by min_factor and max_factor, keeping both bounds at least min_radius from the initial condition (while not crossing 0). Thus, if independent variable \( x_j \) is positive, the bounds will be \( x_j \in [L_j, R_j] \) where \( L_j = \max(0, \min(x_j - \mathtt{min\_radius}, x_j \, \mathtt{min\_factor})) \) and \( R_j = \max(x_j + \mathtt{min\_radius}, x_j \, \mathtt{max\_factor}) \). If independent variable \( x_j \) is negative, the bounds will be \( x_j \in [L_j, R_j] \) where \( L_j = \min(x_j - \mathtt{min\_radius}, x_j \, \mathtt{max\_factor}) \) and \( R_j = \min(0, \max(x_j + \mathtt{min\_radius}, x_j \, \mathtt{min\_factor})) \). For the special case \(x_j=0\), then the bounds are \( x_j \in [-\mathtt{min\_radius}, \mathtt{min\_radius}] \).

Note that not every optimization algorithm allows bound constraints. If bound constraints have been turned on with this subroutine and mango::Problem::optimize is called, MANGO will check whether the selected algorithm supports bound constraints. If not, a warning message will be printed to stdout, and the optimization will proceed, ignoring the bound constraints.

Parameters

min_factor	See description above. The value must lie in [0,1] or else a C++ exception will be thrown.
max_factor	See description above. The value must be \( \ge 1 \), or else a C++ expection will be thrown.
min_radius	See description above. The value must be \( \ge 0 \), or else a C++ exception will be thrown.
preserve_sign	See description above.

Definition at line 126 of file Problem.cpp.

◆ set_user_data()

void mango::Problem::set_user_data ( void * user_data )

Pass the prescribed pointer to the objective function whenever it is called.

This method allows any data structure to be passed to the objective function.

Parameters

[in] user_data A pointer to any data (you can cast any pointer to type void*).

Definition at line 85 of file Problem.cpp.

◆ set_verbose()

void mango::Problem::set_verbose ( int verbose )

Control how much diagnostic information is printed by MANGO.

This diagnostic information may be helpful for debugging.

Parameters

[in] verbose If <= 0, no diagnostic information will be printed. If >0, diagnostic information will be printed.

Definition at line 77 of file Problem.cpp.

Friends And Related Function Documentation

◆ Solver

friend class Solver

friend

Definition at line 443 of file mango.hpp.

Member Data Documentation

◆ mpi_partition

MPI_Partition mango::Problem::mpi_partition

Definition at line 449 of file mango.hpp.

◆ solver

Solver* mango::Problem::solver

protected

Definition at line 446 of file mango.hpp.

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

/home/runner/work/mango/mango/src/api/mango.hpp
/home/runner/work/mango/mango/src/api/algorithms.cpp
/home/runner/work/mango/mango/src/api/Problem.cpp
/home/runner/work/mango/mango/src/api/read_input_file.cpp

Public Member Functions

Public Attributes

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Problem()

◆ ~Problem()

Member Function Documentation

◆ get_best_function_evaluation()

◆ get_function_evaluations()

◆ get_N_parameters()

◆ get_solver()

◆ get_state_vector()

◆ mpi_init()

◆ optimize()

◆ read_input_file()

◆ set_algorithm() [1/2]

◆ set_algorithm() [2/2]

◆ set_bound_constraints()

◆ set_centered_differences()

◆ set_finite_difference_step_size()

◆ set_max_function_evaluations()

◆ set_N_line_search()

◆ set_output_filename() [1/2]

◆ set_output_filename() [2/2]

◆ set_relative_bound_constraints()

◆ set_user_data()

◆ set_verbose()

Friends And Related Function Documentation

◆ Solver

Member Data Documentation

◆ mpi_partition

◆ solver