This Fortran module provides the Fortran API for calling MANGO from outside applications. More...
Functions/Subroutines | |
| subroutine | mango_problem_create (this, N_parameters, state_vector, objective_function) |
| Create a standard (i.e. non-least-squares) optimization problem. More... | |
| subroutine | mango_problem_create_least_squares (this, N_parameters, state_vector, N_terms, targets, sigmas, best_residual_function, residual_function) |
| Create a least-squares optimization problem. More... | |
| subroutine | mango_problem_destroy (this) |
| Delete an optimization problem, freeing memory used internally by MANGO. More... | |
| subroutine | mango_set_algorithm (this, algorithm) |
| Sets the optimization algorithm. More... | |
| subroutine | mango_set_algorithm_from_string (this, algorithm_str) |
| Sets the optimization algorithm. More... | |
| subroutine | mango_read_input_file (this, filename) |
| Reads in the number of worker groups and algorithm from a file. More... | |
| subroutine | mango_set_output_filename (this, filename) |
| Sets the name of the output file that will record values of the objective function at each evaluation. More... | |
| subroutine | mango_mpi_init (this, mpi_comm) |
| Initialize MANGO's internal MPI data that describes the partitioning of the processes into worker groups. More... | |
| subroutine | mango_mpi_partition_set_custom (this, comm_world, comm_group_leaders, comm_worker_groups) |
| Use a user-supplied partitioning of the MPI processes into worker groups. More... | |
| subroutine | mango_set_n_worker_groups (this, N_worker_groups) |
| Set the number of worker groups. More... | |
| integer function | mango_get_n_worker_groups (this) |
| Get the number of worker groups. More... | |
| double precision function | mango_optimize (this) |
| Carry out the optimization. More... | |
| integer function | mango_get_mpi_rank_world (this) |
| Get the MPI rank of this processor in MANGO's world communicator. More... | |
| integer function | mango_get_mpi_rank_worker_groups (this) |
| Get the MPI rank of this processor in MANGO's "worker groups" communicator. More... | |
| integer function | mango_get_mpi_rank_group_leaders (this) |
| Get the MPI rank of this processor in MANGO's "group leaders" communicator. More... | |
| integer function | mango_get_n_procs_world (this) |
| Get the number of MPI processors in MANGO's world communicator. More... | |
| integer function | mango_get_n_procs_worker_groups (this) |
| Get the number of MPI processors in the worker group that this processor belongs to. More... | |
| integer function | mango_get_n_procs_group_leaders (this) |
| Get the number of MPI processors in the "group leaders" communicator. More... | |
| logical function | mango_get_proc0_world (this) |
| Determine whether this MPI processor has rank=0 in MANGO's world communicator. More... | |
| logical function | mango_get_proc0_worker_groups (this) |
| Determine whether this MPI processor has rank=0 in MANGO's "worker groups" communicator. More... | |
| integer function | mango_get_mpi_comm_world (this) |
| Get MANGO's "world" MPI communicator. More... | |
| integer function | mango_get_mpi_comm_worker_groups (this) |
| Get MANGO's "worker groups" MPI communicator. More... | |
| integer function | mango_get_mpi_comm_group_leaders (this) |
| Get MANGO's "group leaders" MPI communicator. More... | |
| integer function | mango_get_n_parameters (this) |
| Get the number of independent variables for an optimization problem. More... | |
| integer function | mango_get_n_terms (this) |
| For least-squares optimization problems, get the number of terms that are summed in the objective function. More... | |
| integer function | mango_get_worker_group (this) |
| Determine which worker group this MPI process belongs to. More... | |
| integer function | mango_get_best_function_evaluation (this) |
| For an optimization problem that has already been solved, return the index of the function evaluation corresponding to the optimum. More... | |
| integer function | mango_get_function_evaluations (this) |
| For an optimization problem that has already been solved, return the number of times the objective function was evaluated. More... | |
| subroutine | mango_set_max_function_evaluations (this, N) |
| Set the maximum number of evaluations of the objective function that will be allowed before the optimization is terminated. More... | |
| subroutine | mango_set_centered_differences (this, centered_differences) |
| Control whether 1-sided or centered finite differences will be used to compute derivatives of the objective function. More... | |
| logical function | mango_does_algorithm_exist (algorithm_str) |
| Determine whether MANGO has an optimization algorithm corresponding to the provided string. More... | |
| subroutine | mango_set_finite_difference_step_size (this, finite_difference_step_size) |
| Set an absolute step size for finite difference derivatives. More... | |
| subroutine | mango_set_bound_constraints (this, lower_bounds, upper_bounds) |
| Impose bound constraints on an optimization problem. More... | |
| subroutine | mango_set_verbose (this, verbose) |
| Control how much diagnostic information is printed by MANGO. More... | |
| subroutine | mango_set_print_residuals_in_output_file (this, print_residuals_in_output_file) |
| For least-squares problems, control whether or not to print each individual residual in the MANGO output file. More... | |
| subroutine | mango_set_user_data (this, user_data) |
| Pass a data structure to the objective function whenever it is called. More... | |
| subroutine | mango_stop_workers (this) |
| Tell the worker MPI processes (i.e. those that are not group leaders) that the optimization problem is complete. More... | |
| subroutine | mango_mobilize_workers (this) |
| Tell the worker MPI processes (i.e. those that are not group leaders) to begin an evaluation of the objective function. More... | |
| logical function | mango_continue_worker_loop (this) |
| For an MPI worker, determine whether to carry out another evaluation of the objective function or exit. More... | |
| subroutine | mango_mpi_partition_write (this, filename) |
| Write a file showing the worker group assignments and rank of each process in each MPI communicator. More... | |
| subroutine | mango_set_relative_bound_constraints (this, min_factor, max_factor, min_radius, preserve_sign) |
| Impose bound constraints on an optimization problem, with the bounds chosen as multiples of the initial state vector. More... | |
| subroutine | mango_set_n_line_search (this, N_line_search) |
| Sets the number of points considered as a set for parallel line searches. More... | |
This Fortran module provides the Fortran API for calling MANGO from outside applications.
| logical function mango_mod::mango_continue_worker_loop | ( | type(mango_problem), intent(in) | this | ) |
For an MPI worker, determine whether to carry out another evaluation of the objective function or exit.
This subroutine should only be called on MPI processors that are not group leaders. You can see typical usage of this subroutine in the examples. However you are also free to use your own approach to controlling the worker processes instead of this subroutine.
| this | The optimization problem. |
| logical function mango_mod::mango_does_algorithm_exist | ( | character(len=*), intent(in) | algorithm_str | ) |
| integer function mango_mod::mango_get_best_function_evaluation | ( | type(mango_problem), intent(in) | this | ) |
For an optimization problem that has already been solved, return the index of the function evaluation corresponding to the optimum.
| this | The optimization problem. |
| integer function mango_mod::mango_get_function_evaluations | ( | type(mango_problem), intent(in) | this | ) |
For an optimization problem that has already been solved, return the number of times the objective function was evaluated.
| this | The optimization problem. |
| integer function mango_mod::mango_get_mpi_comm_group_leaders | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_mpi_comm_worker_groups | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_mpi_comm_world | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_mpi_rank_group_leaders | ( | type(mango_problem), intent(in) | this | ) |
Get the MPI rank of this processor in MANGO's "group leaders" communicator.
| this | The optimization problem. |
| integer function mango_mod::mango_get_mpi_rank_worker_groups | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_mpi_rank_world | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_n_parameters | ( | type(mango_problem), intent(in) | this | ) |
Get the number of independent variables for an optimization problem.
| this | The mango_problem object to query. |
| integer function mango_mod::mango_get_n_procs_group_leaders | ( | type(mango_problem), intent(in) | this | ) |
Get the number of MPI processors in the "group leaders" communicator.
| this | The optimization problem. |
| integer function mango_mod::mango_get_n_procs_worker_groups | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_n_procs_world | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_n_terms | ( | type(mango_problem), intent(in) | this | ) |
For least-squares optimization problems, get the number of terms that are summed in the objective function.
| this | The mango_problem object to query. |
| integer function mango_mod::mango_get_n_worker_groups | ( | type(mango_problem), intent(in) | this | ) |
| logical function mango_mod::mango_get_proc0_worker_groups | ( | type(mango_problem), intent(in) | this | ) |
Determine whether this MPI processor has rank=0 in MANGO's "worker groups" communicator.
| this | The optimization problem. |
| logical function mango_mod::mango_get_proc0_world | ( | type(mango_problem), intent(in) | this | ) |
| integer function mango_mod::mango_get_worker_group | ( | type(mango_problem), intent(in) | this | ) |
Determine which worker group this MPI process belongs to.
| this | The mango_problem object to query. |
| subroutine mango_mod::mango_mobilize_workers | ( | type(mango_problem), intent(in) | this | ) |
Tell the worker MPI processes (i.e. those that are not group leaders) to begin an evaluation of the objective function.
This subroutine should only be called by group leaders. This subroutine is typically called at the beginning of the user-supplied subroutine for the objective function. You can see typical usage of this subroutine in the examples. However you are also free to use your own approach to controlling the worker processes instead of this subroutine.
| this | The optimization problem. |
| subroutine mango_mod::mango_mpi_init | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | 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.
| this | The optimization problem. |
| 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. |
| subroutine mango_mod::mango_mpi_partition_set_custom | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | comm_world, | ||
| integer, intent(in) | comm_group_leaders, | ||
| integer, intent(in) | comm_worker_groups | ||
| ) |
Use a user-supplied partitioning of the MPI processes into worker groups.
Use either this subroutine or mango_mpi_init, not both.
| this | The optimization problem for which you want to set the MPI structures. |
| comm_world | An MPI communicator consisting of all the processors that will participate in the optimization in any way. |
| comm_group_leaders | An MPI communicator consisting only of the group leaders. |
| comm_worker_groups | An MPI communicator containing all the processors of comm_world, but with a separate "color" for each worker group. The processes with rank 0 in this communicator must be the same as the processes in comm_group_leaders. |
| subroutine mango_mod::mango_mpi_partition_write | ( | type(mango_problem), intent(in) | this, |
| character(len=*), intent(in) | filename | ||
| ) |
| double precision function mango_mod::mango_optimize | ( | type(mango_problem), intent(in) | this | ) |
| subroutine mango_mod::mango_problem_create | ( | type(mango_problem), intent(out) | this, |
| integer, intent(in) | N_parameters, | ||
| real(c_double), dimension(:), intent(in) | state_vector, | ||
| procedure(objective_function_interface) | objective_function | ||
| ) |
Create a standard (i.e. non-least-squares) optimization problem.
| this | An object storing the created optimization problem. |
| N_parameters | The number of independent variables. |
| state_vector | An array of size N_parameters, which will be used to store the initial condition. You can set the values of this array either before or after calling this routine, as long as they are set before calling mango_optimize. |
| objective_function | A reference to the objective function that will be minimized. |
| subroutine mango_mod::mango_problem_create_least_squares | ( | type(mango_problem), intent(out) | this, |
| integer, intent(in) | N_parameters, | ||
| real(c_double), dimension(:), intent(in) | state_vector, | ||
| integer, intent(in) | N_terms, | ||
| real(c_double), dimension(:), intent(in) | targets, | ||
| real(c_double), dimension(:), intent(in) | sigmas, | ||
| real(c_double), dimension(:), intent(in) | best_residual_function, | ||
| procedure(vector_function_interface) | residual_function | ||
| ) |
Create a least-squares optimization problem.
| this | An object storing the created optimization problem. |
| N_parameters | The number of independent variables. |
| state_vector | An array of size N_parameters, which will be used to store the initial condition. You can set the values of this array either before or after calling this routine, as long as they are set before calling mango_optimize. |
| N_terms | The number of terms that are summed in the objective function, i.e. the number of elements in the residual vector. |
| targets | An array of size N_terms, storing the target values of each residual function. |
| sigmas | An array of size N_terms, storing the scaling factors for each term in the residual function. |
| best_residual_function | An array of size N_terms. When mango_optimize concludes successfully, this array will store the values of the residuals for the optimum point. |
| residual_function | A reference to the subroutine that computes the residuals. |
| subroutine mango_mod::mango_problem_destroy | ( | type(mango_problem), intent(inout) | this | ) |
| subroutine mango_mod::mango_read_input_file | ( | type(mango_problem), intent(in) | this, |
| character(len=*), intent(in) | 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.
| this | The optimization problem. |
| filename | The filename of the file to read. |
| subroutine mango_mod::mango_set_algorithm | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | algorithm | ||
| ) |
Sets the optimization algorithm.
Note the related subroutine mango_set_algorithm_from_string.
| this | The optimization problem to modify. |
| algorithm | One of the enumerated constants representing optimization algorithms. If the integer supplied is too large or too small, a C++ exception will be thrown. |
| subroutine mango_mod::mango_set_algorithm_from_string | ( | type(mango_problem), intent(in) | this, |
| character(len=*), intent(in) | algorithm_str | ||
| ) |
Sets the optimization algorithm.
Note the related subroutine mango_set_algorithm.
| this | The optimization problem to modify. |
| 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. |
| subroutine mango_mod::mango_set_bound_constraints | ( | type(mango_problem), intent(in) | this, |
| double precision, dimension(:), intent(in) | lower_bounds, | ||
| double precision, dimension(:), intent(in) | upper_bounds | ||
| ) |
Impose bound constraints on an optimization problem.
Note that not every optimization algorithm allows bound constraints. If bound constraints have been turned on with this subroutine and mango_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.
| this | The optimization problem to modify |
| lower_bounds | An array of size N_parameters, giving the lower bound for each independent variable. |
| upper_bounds | An array of size N_parameters, giving the upper bound for each independent variable. |
| subroutine mango_mod::mango_set_centered_differences | ( | type(mango_problem), intent(in) | this, |
| logical, intent(in) | centered_differences | ||
| ) |
Control whether 1-sided or centered finite differences will be used to compute derivatives of the objective function.
| this | The optimization problem. |
| 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). |
| subroutine mango_mod::mango_set_finite_difference_step_size | ( | type(mango_problem), intent(in) | this, |
| double precision, intent(in) | finite_difference_step_size | ||
| ) |
| subroutine mango_mod::mango_set_max_function_evaluations | ( | type(mango_problem), intent(in) | this, |
| integer(c_int), intent(in) | N | ||
| ) |
Set the maximum number of evaluations of the objective function that will be allowed before the optimization is terminated.
| this | The optimization problem. |
| 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. |
| subroutine mango_mod::mango_set_n_line_search | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | 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.
| this | The optimization problem to control |
| N_line_search | The number of points considered as a set for parallel line searches. |
| subroutine mango_mod::mango_set_n_worker_groups | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | N_worker_groups | ||
| ) |
| subroutine mango_mod::mango_set_output_filename | ( | type(mango_problem), intent(in) | this, |
| character(len=*), intent(in) | filename | ||
| ) |
Sets the name of the output file that will record values of the objective function at each evaluation.
| this | The optimization problem |
| filename | A string giving the filename to use for the output file. If the file already exists, it will be over-written. |
| subroutine mango_mod::mango_set_print_residuals_in_output_file | ( | type(mango_problem), intent(in) | this, |
| logical, intent(in) | print_residuals_in_output_file | ||
| ) |
For least-squares problems, control whether or not to print each individual residual in the MANGO output file.
You may wish to print this information to see the relative magnitude of each term in the objective function. On the other hand, for problems with many terms, you may wish to suppress this information to make the file more readable.
| this | The optimization problem to control. If the problem is not a least-squares problem, something bad is likely to happen, like a segmentation fault. |
| print_residuals_in_output_file | Whether or not to print every residual term in the output file. |
| subroutine mango_mod::mango_set_relative_bound_constraints | ( | type(mango_problem), intent(in) | this, |
| real(c_double), intent(in) | min_factor, | ||
| real(c_double), intent(in) | max_factor, | ||
| real(c_double), intent(in) | min_radius, | ||
| logical, intent(in) | 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_set_bound_constraints, so MANGO has pointers to the arrays allocted by the user for lower and upper bounds. mango_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_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.
| this | The optimization problem to modify |
| 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. |
| subroutine mango_mod::mango_set_user_data | ( | type(mango_problem), intent(in) | this, |
| type(c_ptr), intent(in) | user_data | ||
| ) |
Pass a data structure to the objective function whenever it is called.
| this | The optimization problem to modify. |
| user_data | A pointer to the variable or data structure you want to pass to the objective function. To find this pointer, apply the C_LOC function to your variable. C_LOC is available in the standard ISO_C_BINDING module. |
| subroutine mango_mod::mango_set_verbose | ( | type(mango_problem), intent(in) | this, |
| integer, intent(in) | verbose | ||
| ) |
Control how much diagnostic information is printed by MANGO.
This diagnostic information may be helpful for debugging.
| this | The optimization problem to control |
| verbose | If <= 0, no diagnostic information will be printed. If >0, diagnostic information will be printed. |
| subroutine mango_mod::mango_stop_workers | ( | type(mango_problem), intent(in) | this | ) |
Tell the worker MPI processes (i.e. those that are not group leaders) that the optimization problem is complete.
This subroutine should only be called by group leaders. This subroutine is typically called immediately after mango_optimize. You can see typical usage of this subroutine in the examples. However you are also free to use your own approach to stopping the worker processes instead of this subroutine.
| this | The optimization problem. |