! genopt_interface.f (version 20160221)
! (C) 2015-2016 Roberto Battiti and Mauro Brunato, all rights reserved.
! Error codes. Returned by genopt_init() and genopt_terminate().
INTEGER, PARAMETER :: GENOPT_OK = 0 ! No error
INTEGER, PARAMETER :: GENOPT_ERROR_INDEX = 1 ! genopt_init
INTEGER, PARAMETER :: GENOPT_ERROR_SEED = 2 ! genopt_init
INTEGER, PARAMETER :: GENOPT_ERROR_FILE = 3 ! genopt_init, genopt_terminate
INTERFACE
! Initialize the library. To be called once, before any other function in the library.
! Opens report file "genopt_[index]_[seed].txt" for writing.
!
! Parameters:
! function_index: function type ID; see the genopt.pdf manifesto for details.
! function_seed: positive integer that identifies an instance.
!
! Returns:
! GENOPT_OK if no error
! GENOPT_ERROR_INDEX if function with declared function_index does not exist
! GENOPT_ERROR_SEED if seed provided is not positive.
! GENOPT_ERROR_FILE if filename "genopt_[index]_[seed].txt" cannot be created or written.
!
! Preconditions:
! - no other genopt_*() call has been issued (unchecked);
! - function_index must refer to an existing function (checked; returns GENOPT_ERROR_INDEX);
! - function_seed must be positive (checked; returns GENOPT_ERROR_SEED)
! - file "genopt_[index]_[seed].txt" must have create, read, and write permissions
! (checked; returns GENOPT_ERROR_FILE)
FUNCTION genopt_init(function_index, function_seed)
INTEGER :: genopt_init
INTEGER :: function_index, function_seed
END FUNCTION genopt_init
! Get the number of dimensions in function domain.
!
! Returns:
! number of dimensions, depending on function ID on init.
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
FUNCTION genopt_get_dimension()
INTEGER :: genopt_get_dimension
END FUNCTION genopt_get_dimension
! Get the domain limits.
!
! Parameters:
! xmin, xmax: double precision arrays to contain the lower and upper
! domain bounds for each dimension
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
! - xmin and xmax must have been allocated with at least "dimension" elements each.
!
! Notes:
! - Unlike its C counterpart, the Fortran main program must allocate
! enough space in the xmin and xmax vectors, which will be filled up with
! the domain's lower and upper limits
SUBROUTINE genopt_get_domain_limits(xmin,xmax)
REAL*8, dimension(:) :: xmin
REAL*8, dimension(:) :: xmax
END SUBROUTINE genopt_get_domain_limits
! Get the function's global minimum value.
!
! Returns:
! the function's global minimum value.
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
FUNCTION genopt_get_global_minimum()
REAL*8 :: genopt_get_global_minimum
END FUNCTION genopt_get_global_minimum
! Get the number of evaluations performed up to now.
!
! Returns:
! number of evaluations, increases by one each time genopt_evaluate() is called.
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
FUNCTION genopt_get_number_of_evaluations()
INTEGER :: genopt_get_number_of_evaluations
END FUNCTION genopt_get_number_of_evaluations
! Evaluate the function at the given point in the domain.
!
! Parameters:
! - x: evaluation point.
!
! Returns:
! Function value
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
! - input array x must contain (at least) as many values as domain dimension (unchecked).
! - input array x must be within the function's domain (unchecked).
!
! Notes:
! - Although we try to ensure a nice behavior, the outcome of the function
! for values of x outside the domain is undefined
! (may include NaN, Inf, illegal or random value could be returned; function may not terminate)
! - If less that "dimension" cells are allocated for x, memory faults could be generated.
FUNCTION genopt_evaluate(x)
REAL*8 :: genopt_evaluate
REAL*8, dimension(:) :: x
END FUNCTION genopt_evaluate
! Set the maximum number of evaluations; when the limit is reached,
! the report is written and the program is terminated.
!
! Parameters:
! - nev: maximum number of evaluations. Originally set to 0 (unlimited)
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
! - nev >= 0 (unchecked).
SUBROUTINE genopt_set_maximum_number_of_evaluations(nev)
INTEGER :: nev
END SUBROUTINE genopt_set_maximum_number_of_evaluations
! Complete the report file and free all genopt resources.
!
! Returns:
! GENOPT_OK if no error
! GENOPT_ERROR_FILE if filename cannot be written.
!
! Preconditions:
! - genopt_init must have been called returning GENOPT_OK (unchecked).
! - filename must have write permissions (checked; returns GENOPT_ERROR_FILE)
FUNCTION genopt_terminate()
INTEGER :: genopt_terminate
END FUNCTION genopt_terminate
END INTERFACE