bam.minimize follows the scipy.optimize.minimize calling convention and returns an OptimizeResult. We solve the Six-Hump Camel problem of Section 5.1 using:

import bam

def camel6(x):
    x1, x2 = x
    return ((4 - 2.1*x1**2 + x1**4/3) * x1**2
            + x1*x2 + (-4 + 4*x2**2) * x2**2)

res = bam.minimize(camel6, x0=[0, 0],
                   bounds=[(-3, 3), (-1.5, 1.5)],
                   options={"max_evals": 120})
print(res.x, res.fun, res.message)

Users provide bounds as (low, high) pairs or as a scipy.optimize.Bounds object. They are important, yet optional: as in the C API and the full-control Bam class, omitting them lets BAM apply its default MAXBOUND box. When users omit bounds, minimize infers the number of variables from x0, and AskTell from its nvars argument. Users declare integer and categorical variables with integrality=[0, 1, …]. Because the signature is SciPy-compatible, users can also plug BAM into SciPy as a method: scipy.optimize.minimize(fun, x0, method=bam.minimize).

bam.Bam is a thin, faithful mirror of BAM’s C API, for callers who want full control over every option and over the listing, trace, and evaluations files. The objective is a Python callable taking a NumPy array and returning a float; option names and meanings are exactly those of the command-line and C/Fortran interfaces (Section 6). The bounds xmin/xmax are optional, and users declare integer variables with set_int_vector("xisint", …).

By default the objective is single-point: set_objective(fn) registers a callable fn(x) that receives one point (a length-nvars array) and returns one value, exactly as minimize uses it. To match the simulator parallelism declared by the BATCHSIZE option, register a batch objective with set_objective(fn, batch=True): fn then receives a writable (k, nvars) array of k points and returns k objective values, where k is the value of BATCHSIZE. BAM currently caps BATCHSIZE at 1, so k remains 1 until developers raise that cap; the batch form ensures that callers can write code once and maintain compatibility later.

# library version number (year, month, day)
print("BAM library build:", bam.Bam.get_solver_version())

with bam.Bam(nvars=2) as solver:
    solver.set_real_vector("xmin", [-3.0, -1.5])
    solver.set_real_vector("xmax", [ 3.0,  1.5])
    solver.set_real_vector("rho",  [1e-3, 1e-3])   # per-variable resolution
    solver.set_int("maxevals", 80)
    solver.set_string("proname",    "camel6")      # names the run
    solver.set_string("outfname",   "camel6.lst")  # mirror screen output
    solver.set_string("tracefname", "camel6.trc")  # one-line run summary
    solver.set_objective(camel6)
    result = solver.solve(x0=[0.0, 0.0])

print(result.x, result.fun, result.nfev)

By default the wrapper writes none of BAM’s output files and suppresses any local bam.opt. The scalar string setters above turn them on, with exactly the meaning the corresponding options carry from the command line: a listing file (outfname) that mirrors the screen output, and a trace file (tracefname) that receives one comma-separated summary line per run, appended on each subsequent run (see Section 7). The proname option names the run in that file. The rho vector sets the per-variable resolution, the smallest spacing BAM resolves between proposed points; the ${10}^{-3}$ used here is why the best value below ($-1.0316264$) is marginally coarser than camel6’s optimum near $-1.0316285$ (the default resolution is ${10}^{-8}$). For the solve above, camel6.trc contains:

#proname, BAMVersion, TotalTime, best_f, SolverEvals, best_eval, Incumbent progression, BAMStatus
camel6, BAM-2026.5.21, 0.44615474, -1.0316264, 80, 51, -1.0316248, 35

The header names the comma-separated fields: the run name (proname), the BAM version, the total CPU time, the best objective value, the number of function evaluations, the evaluation at which the incumbent was found, the incumbent progression (one value every PRBESTFREQ evaluations, 50 by default), and the termination code (35 here, meaning the function-call limit was reached). Every field except the time is deterministic; TotalTime depends on the wall-clock and varies between machines and runs.

The minimize function and the Bam class both work by calling the objective: the caller hands BAM a Python function, and BAM invokes that function whenever it needs an objective value. BAM owns the loop. This is the natural pattern when the objective is an ordinary computation that returns promptly.

Some objectives do not fit that pattern. The evaluation may be a physical experiment performed by a person over hours or days; it may be a simulation dispatched to a separate cluster, where a job is queued and results return later; or it may live in another process, another language, or a piece of laboratory equipment. In these cases there is no Python callable for BAM to invoke, and BAM cannot block inside a callback waiting for a result that is hours away.

The AskTell interface inverts the control flow for exactly these situations. Instead of BAM calling the objective, the caller repeatedly asks BAM which point to evaluate next, performs the evaluation by whatever means is appropriate, and then tells BAM the resulting value. The caller owns the loop; BAM only advises. Arbitrary time, and arbitrary work, may pass between an ask and the corresponding tell.

opt = bam.AskTell(nvars=2, bounds=[(-3, 3), (-1.5, 1.5)],
                  max_evals=120)
while not opt.is_done():
    try:
        x = opt.ask()
    except StopIteration:
        break
    opt.tell(x, camel6(x))
res = opt.recommendation()
opt.close()

Here, camel6(x) is used only to keep the example self-contained; in practice the line opt.tell(x, camel6(x)) would be replaced by running the actual experiment or simulation on the point x and reporting the measured objective value. The interface consists of ask(), which returns the next point to evaluate as a NumPy array; tell(x, f), which reports that the objective value at x is f; is_done(), which reports whether BAM has finished; recommendation(), which returns the best point found so far as an OptimizeResult; and close(), which shuts the optimizer down and releases its resources. Using AskTell as a context manager calls close() automatically.

BAM runs in free mode for problems with at most bam.license_status()["free_limit_nvars"] variables and requires a license above that limit. The license is a run-time concern and is never part of the installed package. Point BAM at a license either with the environment variable BAM_LICENSE_FILE or programmatically:

import bam
bam.set_license_file("/path/to/bamlice.txt")
status = bam.license_status()
# status -> {"state": "licensed" | "free_no_license" | ...,
#            "path": ..., "free_limit_nvars": 2}

set_license_file raises bam.BamLicenseError immediately if the file does not exist. In free mode, the wrapper emits a bam.BamLicenseWarning and, for a problem larger than the free limit, raises bam.BamLicenseError at solve time.

bam.__version__ reports the version of the installed package. license_status() reports the live license state as above. Every solve returns an OptimizeResult whose status and message fields carry BAM’s termination code and its canonical text, queried from libbam so that they never drift from the installed library version. A callback that raises propagates the exception out of solve with the partial OptimizeResult attached; a callback that returns NaN is recorded by BAM as $+\mathrm{\infty }$ and the search continues.

The Python layer relies on a flag-and-poll interrupt architecture detailed in Section 8.5: a Ctrl-C during a solve raises bam.BamInterrupted carrying the best result found so far (for AskTell, the interruption is surfaced through recommendation() with termination code 50). BAM saves and restores the host’s signal dispositions around each solve, so a Python signal handler installed by the caller survives. The package is fully deterministic and has no seed parameter.

Each routine listed here is available in two versions:

• •

  A C-compatible routine: bam_xxx

• •

  A native Fortran routine: bam_xxx_f

• •

  bam_create(nvars)
  Create a new optimization problem with nvars variables.

• •

  bam_destroy()
  Destroy the current problem and free memory.

• •

  bam_solve(x_best, f_best, start)
  Solve the optimization problem.

• •

  bam_set_int(name, value)

• •

  bam_set_int_vector(name, values, n)

• •

  bam_set_real(name, value)

• •

  bam_set_real_vector(name, values, n)

• •

  bam_set_real_matrix_column(name, values, n, k)

• •

  bam_set_string(name, value)

• •

  bam_set_string_vector(name, values)

All these functions utilize native C data types. Each function has a corresponding _f version using native Fortran types.

• •

  bam_set_obj_fun(fproc, user_data)
  Register an objective function using a C-interoperable callback.

• •

  bam_set_obj_fun_f(fproc, user_data)
  Register an objective function using a native Fortran callback.

The bam_set_obj_fun(fproc, user_data) callback has the signature:

subroutine f(n, k, x, fval, terminate, user_data) bind(C)
    use iso_c_binding
    integer(c_int), value :: n
    integer(c_int)        :: k
    real(c_double)        :: x(*)
    real(c_double)        :: fval(*)
    integer(c_int)        :: terminate
    type(c_ptr), value    :: user_data
end subroutine

The signature of bam_set_obj_fun_f(fproc, user_data) is similar:

subroutine f(n, k, x, fval, terminate, user_data)
    use iso_c_binding
    integer            :: n, k
    real               :: x(*)
    real               :: fval(*)
    integer            :: terminate
    type(c_ptr), value :: user_data
end subroutine

Here, n is the number of variables and k the number of points to evaluate: x holds n*k reals (point j occupying x((j-1)*n+1:j*n)) and may be modified by the callback, while fval holds the k objective values. k is capped by the BATCHSIZE option and is currently always 1; it is passed by reference so a future multi-point design may let the callback change it. The terminate argument is an output of the callback. On entry, it is 0; the callback writes the objective value(s) to fval and leaves terminate at 0 to ask BAM to continue. To request a clean termination from inside the callback, the user sets terminate to a nonzero value; fval is then ignored, BAM populates x_best/f_best with the best evaluation seen so far, and returns from bam_solve with termination code 51 (see Section 7 item 51). This termination condition is distinct from code 50 “Run interrupted by user”, which is reserved for OS-level signals such as SIGINT/SIGTERM.

• •

  real(c_double) function bam_get_time()

• •

  integer(c_int) function bam_get_calls()

• •

  void bam_get_version(yr,mo,da)

• •

  integer(c_int) function bam_get_status_count()

• •

  void bam_get_status_message(status, buffer, buflen)

• •

  integer(c_int) function bam_get_license_state()

• •

  void bam_get_license_path(buffer, buflen)

• •

  integer(c_int) function bam_get_free_mode_nvars()

The _f functions are native Fortran functions, i.e.:

• •

  real function bam_get_time_f()

• •

  integer function bam_get_calls_f()

• •

  subroutine bam_get_version_f(yr,mo,da)

• •

  integer function bam_get_status_count_f()

• •

  subroutine bam_get_status_message_f(status, message)

• •

  integer function bam_get_license_state_f()

• •

  subroutine bam_get_license_path_f(path)

• •

  integer function bam_get_free_mode_nvars_f()

The two bam_get_status_* routines let any caller query BAM’s termination/error code messages at runtime, so external code need not duplicate the message list maintained inside the library. bam_get_status_count returns the total number of codes (i.e., the upper bound on valid status arguments); bam_get_status_message writes the human-readable text for a given code into a caller-provided buffer (C: null-terminated; Fortran: blank-padded). Out-of-range codes (including 0, which BAM does not use) return the sentinel string Unknown status code.. The full list of messages is given in Section 9.

The three bam_get_license_* and the related bam_get_free_mode_nvars routines expose the licensing state to API callers without forcing them to scrape the listing file.

bam_get_license_state reports which of the three states applies given the currently configured license-file name: 0 for licensed (a valid license file was found), 1 for free mode with no license file configured anywhere on the search path, and 2 for free mode with a license file that was found but is unusable (cannot open, malformed, or for a different BAM version). The routine performs a fresh, quiet license check at call time and may therefore be invoked at any point in the API lifecycle, including before bam_create.

bam_get_license_path writes the resolved license-file path into a caller-provided buffer; when the file is found anywhere on the search path (CWD, executable directory, or $PATH) the buffer receives the full resolved path, and when not found, it receives the configured name unchanged, so callers can see what was searched for. The C variant null-terminates and truncates to fit; the Fortran variant blank-pads per Fortran assignment semantics.

bam_get_free_mode_nvars returns the maximum number of problem variables BAM allows in free (unlicensed) mode. At the time of this writing, that value is 2; reading it via this entry point insulates the host applications from future tier changes.

The license-file name BAM searches for is stored internally as licfname and defaults to bamlice.txt. Callers can override the name (or pin an absolute path) via

bam_set_string("licfname", "/absolute/or/altname.txt");

This is one of two keywords that bam_set_string accepts before bam_create (the other being optfname); calling it after bam_create also works.

Once a caller has set licfname, the value applies to every subsequent invocation of BAM in the same process until the caller changes it again with another bam_set_string("licfname", …) call. In particular, licfname is deliberately preserved across bam_destroy / bam_create cycles. It is a process-level configuration (which license file to read for this installation), not per-problem state. A host application or language wrapper that pins a custom license file path once does not have to reapply it on every solve.

The matching policy applied at solve time is: a licensed problem prints the Licensee: banner and runs; a free-with-no-file problem with at most bam_get_free_mode_nvars() variables runs silently while a larger one returns status 9 code 1; a free-with-invalid-file problem with at most bam_get_free_mode_nvars() variables emits a warning and runs, while a larger one returns status 9 code 2.

The options-file name BAM reads at the start of every solve is stored internally as optfname and defaults to bam.opt (looked up in the execute directory). Callers can override the name, point BAM at an alternate options file, or suppress the lookup entirely via

bam_set_string("optfname", "/absolute/path/or/altname.opt");
bam_set_string("optfname", "");   /* suppress bam.opt lookup */

This is the second of the two keywords that bam_set_string accepts before bam_create (the other being licfname); calling it after bam_create also works. Unlike every other bam_set_string keyword, optfname accepts an empty value, which is the recommended setting in API drivers that should ignore any local bam.opt file (see the OPTFNAME row of the options table in Section 6 and the Warning attached to it). The options it would have read are, in every case, settable through the API directly, so suppressing bam.opt does not lose functionality.

C users include the header (the contents of bam.h are reproduced in Appendix A):

#include "bam.h"

A typical usage pattern is:

int n = 2;
double xbest[2], fbest;
bam_create(n);

bam_set_real_vector("xmin", xmin, n);
bam_set_real_vector("xmax", xmax, n);

bam_set_obj_fun(myfun, mydata);

bam_solve(xbest, &fbest, 0);
bam_destroy();

The callback has the signature:

void myfun(int n, int *k, double *x, double *f,
           int *terminate, void *user_data);

Here, n is the number of variables and *k is the number of points to evaluate: x holds n*(*k) doubles, point j occupying x[j*n .. j*n+n-1], and the callback writes one objective value per point into f[0 .. *k-1]. x is writable, so the callback may overwrite a point (for example, because it was only able to compute the objective at a nearby point). *k is capped by the BATCHSIZE option and is currently always 1 (BATCHSIZE is capped at 1 in this release); k is passed by reference so that a future multi-point design may let the callback modify it in case the user chooses to return fewer or more points than as many were requested by BAM. User data is passed as a void* and forwarded to the callback. The terminate argument is an output of the callback: on entry *terminate is 0; setting it to a nonzero value asks BAM to stop the run cleanly (f is then ignored), causing bam_solve to return termination code 51.

The following driveroptimizes the Six-Hump Camel function. It illustrates the complete sequence of API calls, including full error checking.

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include "bam.h"

/* ================================================================
   camel6 objective function callback
   ================================================================ */
void camel6(int n, int *k, double *x, double *f,
            int *terminate, void *user_data)
{
  (void)user_data;
  /* Evaluate camel6 at each of the *k requested points (currently *k == 1).
     Point j occupies x[j*n .. j*n+n-1]; its value goes into f[j]. */
  for (int j = 0; j < *k; ++j) {
    double x1 = x[j*n], x2 = x[j*n + 1];
    f[j] = 4.*x1*x1 - 2.1*pow(x1, 4.) + 0.3333333333333333*pow(x1, 6.)
      + x1*x2 - 4.*x2*x2 + 4.*pow(x2, 4.);
  }
  *terminate = 0;
}

/* ================================================================
   Main program
   ================================================================ */
int main(void)
{
  int nvars = 2;
  int status;

  double xbest[2];
  double fbest;

  double xmin[2] = {-3, -1.5};
  double xmax[2] = {3, 1.5};

  int dummy = 0;   /* user data */
  void *pUser = &dummy;

  /* --------------------------------------------------------------
       Create BAM problem
     -------------------------------------------------------------- */
  status = bam_create(nvars);
  if (status != 0) {
    printf("bam_create failed, status=%d\n", status);
    return 1;
  }

  /* --------------------------------------------------------------
     Set bounds
     -------------------------------------------------------------- */
  status = bam_set_real_vector("xmin", xmin, nvars);
  if (status != 0) {
    printf("bam_set_real_vector failed, status=%d\n", status);
    return 1;
  }
  status = bam_set_real_vector("xmax", xmax, nvars);
  if (status != 0) {
    printf("bam_set_real_vector failed, status=%d\n", status);
    return 1;
  }

  /* --------------------------------------------------------------
     Set filenames
     -------------------------------------------------------------- */
  status = bam_set_string("outfname", "camel6.lst");
  if (status != 0) {
    printf("bam_set_string failed, status=%d\n", status);
    return 1;
  }
  status = bam_set_string("tracefname", "camel6.trc");
  if (status != 0) {
    printf("bam_set_string failed, status=%d\n", status);
    return 1;
  }

  /* --------------------------------------------------------------
     Register objective function
     -------------------------------------------------------------- */
  status = bam_set_obj_fun(camel6, pUser);
  if (status != 0) {
    printf("bam_set_obj_fun failed, status=%d\n", status);
    return 1;
  }

  /* --------------------------------------------------------------
     Initial guess
     -------------------------------------------------------------- */
  xbest[0] = 0;
  xbest[1] = 0;
  int start_at_xbest = 1;

  /* --------------------------------------------------------------
     Solve
     -------------------------------------------------------------- */
  status = bam_solve(xbest, &fbest, start_at_xbest);

  int i;
  printf("Status = %d\n", status);
  printf("Best f = %.15e\n", fbest);
  printf("Best x = ");
  for (i = 0; i < nvars; i++) printf("%.15e ", xbest[i]);
  printf("\n");

  /* --------------------------------------------------------------
  Destroy
  -------------------------------------------------------------- /
  status = bam_destroy();
  if (status != 0) {
    printf("bam_destroy failed, status=%d\n", status);
    return 1;
  }

  return 0;
}

After bam_solve returns, the utility routines provide diagnostic information that is useful for benchmarking and reproducibility. They may be called as follows:

int yr, mo, da;
bam_get_version(&yr, &mo, &da);
printf("BAM version %d.%d.%d\n", yr, mo, da);
printf("Solved in %d calls and %.3f s\n",
       bam_get_calls(), bam_get_time());

The same utility routines exist as native-Fortran functions bam_get_version_f, bam_get_calls_f, and bam_get_time_f.

Fortran users may call the C API directly by including the interface block in bam.inc (reproduced in Appendix B). A callback is written as:

subroutine camel6(n, k, x, f, terminate, user_data) bind(C)
    use iso_c_binding
    integer(c_int), value :: n
    integer(c_int) :: k
    real(c_double) :: x(*), f(*)
    type(c_ptr), value :: user_data
    integer(c_int) :: terminate
end subroutine

User data is passed using c_loc:

integer, target :: id = 7
call bam_set_obj_fun(c_funloc(camel6), c_loc(id))

Inside the callback, user data is recovered using c_f_pointer.

The following driveroptimizes the Six-Hump Camel function via the C API.

module camel6_callbacks
  use iso_c_binding
contains

  !======================================================================
  ! camel6 objective function (C interoperable)
  !======================================================================
  subroutine camel6(n, k, x, f, terminate, user_data) bind(C, name="camel6")
    use iso_c_binding
    implicit none

    integer(c_int), value       :: n
    integer(c_int)              :: k
    real(c_double)              :: x(*)
    real(c_double)              :: f(*)
    integer(c_int), intent(out) :: terminate
    type(c_ptr),    value       :: user_data

    integer        :: j, base
    real(c_double) :: x1, x2

    ! Evaluate camel6 at each of the k requested points (currently k == 1).
    ! Point j occupies x((j-1)*n+1:j*n); its value goes into f(j).
    do j = 1, k
       base = (j-1)*n
       x1 = x(base+1)
       x2 = x(base+2)
       f(j) = 4.d0*x1**2 - 2.1d0*x1**4 + 0.3333333333333333d0*x1**6 &
            + x1*x2 - 4.d0*x2**2 + 4.d0*x2**4
    end do

    terminate = 0

  end subroutine camel6

end module camel6_callbacks

program main
  use iso_c_binding
  use camel6_callbacks
  use iso_fortran_env, only: real64, int32
  implicit none

  include ’bam.inc’

  !--------------------------------------------------------------
  ! Problem size
  !--------------------------------------------------------------
  integer(int32), parameter :: nvars = 2

  ! Variables
  real(c_double) :: xbest(nvars), fbest
  integer(c_int) :: status, start_at_xbest

  ! Bounds
  real(c_double) :: xmin(nvars), xmax(nvars)

  ! Dummy user data
  integer(int32), target :: dummy
  type(c_ptr) :: pUser

  ! C strings
  character(kind=c_char,len=5),  parameter :: c_xmin = ’xmin’//c_null_char
  character(kind=c_char,len=5),  parameter :: c_xmax = ’xmax’//c_null_char
  character(kind=c_char,len=9),  parameter :: &
       c_outfname = ’outfname’//c_null_char
  character(kind=c_char,len=11),  parameter :: &
       c_tracefname = ’tracefname’//c_null_char
  character(kind=c_char,len=11),  parameter :: &
       c_lst = ’camel6.lst’//c_null_char
  character(kind=c_char,len=11),  parameter :: &
       c_trc = ’camel6.trc’//c_null_char

  !--------------------------------------------------------------
  ! Create BAM problem
  !--------------------------------------------------------------
  status = bam_create(nvars)
  if (status /= 0) then
     print *, "bam_create failed, status=", status
     stop
  end if

  !--------------------------------------------------------------
  ! Set bounds
  !--------------------------------------------------------------
  xmin(1) = -3d0
  xmin(2) = -1.5d0
  xmax(1) = 3d0
  xmax(2) = 1.5d0

  status = bam_set_real_vector(c_xmin, xmin, nvars)
  if (status /= 0) then
     print *, "bam_set_real_vector failed, status=", status
     stop
  end if
  status = bam_set_real_vector(c_xmax, xmax, nvars)
  if (status /= 0) then
     print *, "bam_set_real_vector failed, status=", status
     stop
  end if

  !--------------------------------------------------------------
  ! Set filenames
  !--------------------------------------------------------------
  status = bam_set_string(c_outfname, c_lst)
  if (status /= 0) then
     print *, "bam_set_string failed, status=", status
     stop
  end if
  status = bam_set_string(c_tracefname,    c_trc)
  if (status /= 0) then
     print *, "bam_set_string failed, status=", status
     stop
  end if

  !--------------------------------------------------------------
  ! Register objective function
  !--------------------------------------------------------------
  pUser = c_loc(dummy)
  status = bam_set_obj_fun(c_funloc(camel6), pUser)
  if (status /= 0) then
     print *, "bam_set_obj_fun failed, status=", status
     stop
  end if

  !--------------------------------------------------------------
  ! Initial guess
  !--------------------------------------------------------------
  xbest(1:nvars) = 0d0
  start_at_xbest = 1

  !--------------------------------------------------------------
  ! Solve
  !--------------------------------------------------------------
  status = bam_solve(xbest, fbest, start_at_xbest)

  print *, "Status = ", status
  print *, "Best f = ", fbest
  print *, "Best x = ", xbest

  !--------------------------------------------------------------
  ! Destroy
  !--------------------------------------------------------------
  status = bam_destroy()
  if (status /= 0) then
     print *, "bam_destroy failed, status=", status
     stop
  end if

end program main

The native Fortran API provides routines with the suffix _f that use standard Fortran types:

• •

  integer function bam_create_f(nvars)

• •

  integer function bam_set_real_f(name,value)

• •

  integer function bam_solve_f(xbest,fbest,start)

A native Fortran callback has the signature:

subroutine myfun(n, k, x, f, terminate, user_data)
    use iso_c_binding
    implicit none
    integer            :: n, k, terminate
    real               :: x(*), f(*)
    type(c_ptr), value :: user_data
end subroutine

User data is passed using c_loc exactly as in the C API. The terminate argument matches the C-API contract: setting it to a nonzero value asks BAM to stop the run cleanly and return code 51 from bam_solve; the value of f is then ignored.

The native API is convenient for Fortran-only users and avoids bind(C) procedures and data.

The following driveroptimizes the Six-Hump Camel function using the native Fortran API.

      program main
      use iso_c_binding
      use iso_fortran_env, only: real64, int32
      implicit none

C     BAM API declarations
      integer(int32) :: bam_create_f, bam_set_real_vector_f
      integer(int32) :: bam_set_obj_fun_f
      integer(int32) :: bam_set_string_f, bam_solve_f, bam_destroy_f

C     Problem size
      integer, parameter :: nvars = 2

C     Variables
      real(real64) :: xbest(nvars), fbest
      integer(int32) :: status, start_at_xbest

C     Bounds
      real(real64) :: xmin(nvars), xmax(nvars)

C     User data (unused here)
      integer, target :: dummy
      type(c_ptr) :: user_data = c_null_ptr

C     External objective function
      external :: camel6

C     Create BAM problem
      status = bam_create_f(nvars)
      if (status /= 0) then
         print *, ’bam_create_f failed, status=’, status
         stop
      endif

C     Set bounds
      xmin(1) = -3d0
      xmin(2) = -1.5d0
      xmax(1) = 3d0
      xmax(2) = 1.5d0

      status = bam_set_real_vector_f(’xmin’, xmin, nvars)
      if (status /= 0) then
         print *, ’bam_set_real_vector_f failed, status=’, status
         stop
      endif
      status = bam_set_real_vector_f(’xmax’, xmax, nvars)
      if (status /= 0) then
         print *, ’bam_set_real_vector_f failed, status=’, status
         stop
      endif

C     Initialize filenames
      status = bam_set_string_f(’outfname’, ’camel6.lst’)
      if (status /= 0) then
         print *, ’bam_set_string_f failed, status=’, status
         stop
      endif
      status = bam_set_string_f(’scratch’, ’camel6.scr’)
      if (status /= 0) then
         print *, ’bam_set_string_f failed, status=’, status
         stop
      endif
      status = bam_set_string_f(’tracefname’, ’camel6.trc’)
      if (status /= 0) then
         print *, ’bam_set_string_f failed, status=’, status
         stop
      endif

C     Register objective function (Fortran-native)
      status = bam_set_obj_fun_f(camel6, user_data)
      if (status /= 0) then
         print *, ’bam_set_obj_fun_f failed, status=’, status
         stop
      endif

C     Initial guess
      xbest(1:nvars) = 0d0
      start_at_xbest = 1

C     Solve
      status = bam_solve_f(xbest, fbest, start_at_xbest)
      print *, ’Status = ’, status
      print *, ’Best f = ’, fbest
      print *, ’Best x = ’, xbest(1:nvars)

C     Destroy
      status = bam_destroy_f()
      if (status /= 0) then
         print *, ’bam_destroy_f failed, status=’, status
         stop
      endif

      end

C======================================================================
C     camel6 objective function
C======================================================================

      subroutine camel6(n, k, x, f, terminate, user_data)
      use iso_c_binding
      use iso_fortran_env, only: real64, int32
      implicit none
      integer(int32) :: n, k, terminate, j, base
      real(real64) :: x(*), f(*), x1, x2
      type(c_ptr) :: user_data

C     Evaluate camel6 at each of the k requested points (currently k == 1).
C     Point j occupies x((j-1)*n+1:j*n); its value goes into f(j).
      do j = 1, k
         base = (j-1)*n
         x1 = x(base+1)
         x2 = x(base+2)
         f(j) = 4.d0*x1**2 - 2.1d0*x1**4 + 0.3333333333333333d0*x1**6
     $        + x1*x2 - 4.d0*x2**2 + 4.d0*x2**4
      end do

      terminate = 0
      return
      end

This subsection applies to the C and Fortran APIs only. The bam-solver Python package (Section 8.3) ships pre-compiled with the BAM library bundled inside the wheel, so Python users compile and link nothing.

The recommended commands below assume that the BAM include files (bam.h, bam.inc) and shared libraries (libbam.so on Linux, libbam.dylib on macOS, libbam.dll on Windows) are in the current working directory.

icx -g -O3 -fp-model=consistent -ftz -fimf-arch-consistency=true \
    -static-intel -I. -L. \
    camel6.c -lbam -lm \
    -Wl,-rpath,’$ORIGIN’ -o camel6

ifx -g -O3 -fp-model=consistent -ftz -fimf-arch-consistency=true \
    -heap-arrays 1024 -assume noold_maxminloc -static-intel \
    -I. -L. \
    camel6.f -lbam \
    -Wl,-rpath,’$ORIGIN’ -o camel6

gfortran -g -O3 -fno-fast-math -ffp-contract=off \
    -fno-associative-math -fno-reciprocal-math \
    -fmax-stack-var-size=1024 \
    -I. -L. \
    camel6.f -lbam \
    -Wl,-rpath,’$ORIGIN’ -o camel6

ifx -g -O3 -fp-model=consistent -ftz -fimf-arch-consistency=true \
    -heap-arrays 1024 -assume noold_maxminloc -static-intel \
    -I. -L. \
    camel6.f90 -lbam \
    -Wl,-rpath,’$ORIGIN’ -o camel6

The -Wl,-rpath,$ORIGIN linker flag embeds a relative runtime search path so that the resulting executable will find libbam.so in the same directory as the executable itself. This avoids the need to set LD_LIBRARY_PATH at run time.

This section illustrates the application of BAM API to the mixed-integer problem st_e36.

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include "bam.h"

/* ================================================================
   st_e36 objective function callback
   ================================================================ */
void st_e36(int n, int *k, double *x, double *f,
            int *terminate, void *user_data)
{
  (void)user_data;
  /* x[1] is integer */
  #define _SQR(x) ((x)*(x))
  /* Evaluate at each of the *k requested points (currently *k == 1). */
  for (int j = 0; j < *k; ++j) {
    double *xj = x + j*n;
    f[j] = (double)(2*_SQR(xj[0]) + 0.008*pow(xj[1],3)
                    - 3.2*xj[0]*xj[1] - 2*xj[1]);
  }
  *terminate = 0;
}

/* ================================================================
   Main program
   ================================================================ */
int main(void)
{
  int nvars = 2, status;
  double xbest[2], fbest;
  double xmin[2] = {3, 15};
  double xmax[2] = {5.5, 25};
  int    xisint[2] = {0, 1};

  int dummy = 0;
  void *pUser = &dummy;

  status = bam_create(nvars);
  if (status != 0) return 1;

  status = bam_set_real_vector("xmin", xmin, nvars);
  status = bam_set_real_vector("xmax", xmax, nvars);
  status = bam_set_int_vector ("xisint", xisint, nvars);

  status = bam_set_string("outfname",  "st_e36.lst");
  status = bam_set_string("tracefname","st_e36.trc");

  status = bam_set_obj_fun(st_e36, pUser);

  xbest[0] = 4.433315;
  xbest[1] = 18;
  int start_at_xbest = 1;

  status = bam_solve(xbest, &fbest, start_at_xbest);
  printf("Best f = %.15e\n", fbest);
  printf("Best x = [%.15e, %.15e]\n", xbest[0], xbest[1]);

  status = bam_destroy();
  return 0;
}

The corresponding native Fortran and Fortran-90 drivers are provided as st_e36.f and st_e36.f90 at https://minlp.com.