mango::Problem Class Reference

#include <mango.hpp>

Inheritance diagram for mango::Problem:
mango::Least_squares_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...
 
Solverget_solver ()
 Get the Solver object associated with the optimization problem. More...
 

Public Attributes

MPI_Partition mpi_partition
 

Protected Attributes

Solversolver
 

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_parametersNumber of independent variables.
[in]state_vectorAn array of size N_parameters, giving the initial values of the independent variables.
[in]objective_functionThe 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_commThe 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]filenameThe 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]algorithmOne 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_strA 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]lowerAn 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]upperAn 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_differencesIf 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_sizeAn 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]NThe 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_searchThe 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]filenameA 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]filenameA 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_factorSee description above. The value must lie in [0,1] or else a C++ exception will be thrown.
max_factorSee description above. The value must be \( \ge 1 \), or else a C++ expection will be thrown.
min_radiusSee description above. The value must be \( \ge 0 \), or else a C++ exception will be thrown.
preserve_signSee 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_dataA 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]verboseIf <= 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: