callable functions#

    function blls_initialize(T, INT, data, control, status)

Set default control values and initialize private data

Parameters:

data

holds private internal data

control

is a structure containing control information (see blls_control_type)

status

is a scalar variable of type INT that gives the exit status from the package. Possible values are (currently):

0
The import was successful.

    function blls_read_specfile(T, INT, control, specfile)

Read the content of a specification file, and assign values associated with given keywords to the corresponding control parameters. An in-depth discussion of specification files is available, and a detailed list of keywords with associated default values is provided in $GALAHAD/src/blls/BLLS.template. See also Table 2.1 in the Fortran documentation provided in $GALAHAD/doc/blls.pdf for a list of how these keywords relate to the components of the control structure.

Parameters:

control	is a structure containing control information (see blls_control_type)
specfile	is a one-dimensional array of type Vararg{Cchar} that must give the name of the specification file

    function blls_import(T, INT, control, data, status, n, o,
                         Ao_type, Ao_ne, Ao_row, Ao_col, Ao_ptr_ne, Ao_ptr)

Import problem data into internal storage prior to solution.

Parameters:

control	is a structure whose members provide control parameters for the remaining procedures (see blls_control_type)
data	holds private internal data
status	is a scalar variable of type INT that gives the exit status from the package. Possible values are: 1 The import was successful, and the package is ready for the solve phase -1 An allocation error occurred. A message indicating the offending array is written on unit control.error, and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -2 A deallocation error occurred. A message indicating the offending array is written on unit control.error and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -3 The restrictions n > 0, o > 0 or requirement that type contains its relevant string ‘coordinate’, ‘sparse_by_rows’, ‘sparse_by_columns’, ‘dense_by_rows’, or ‘dense_by_columns’; has been violated.
n	is a scalar variable of type INT that holds the number of variables.
o	is a scalar variable of type INT that holds the number of residuals.
Ao_type	is a one-dimensional array of type Vararg{Cchar} that specifies the unsymmetric storage scheme used for the Jacobian $A_o$. It should be one of ‘coordinate’, ‘sparse_by_rows’, ‘sparse_by_columns’, ‘dense_by_rows’, or ‘dense_by_columns’; lower or upper case variants are allowed.
Ao_ne	is a scalar variable of type INT that holds the number of entries in $A_o$ in the sparse co-ordinate storage scheme. It need not be set for any of the other schemes.
Ao_row	is a one-dimensional array of size A_ne and type INT that holds the row indices of $A_o$ in the sparse co-ordinate or sparse column-wise storage scheme. It need not be set for any of the other schemes, and in this case can be C_NULL.
Ao_col	is a one-dimensional array of size A_ne and type INT that holds the column indices of $A_o$ in either the sparse co-ordinate, or the sparse row-wise storage scheme. It need not be set for any of the other schemes, and in this case can be C_NULL.
Ao_ptr_ne	is a scalar variable of type INT, that holds the length of the pointer array if sparse row or column storage scheme is used for $A_o$. For the sparse row scheme, Ao_ptr_ne should be at least o+1, while for the sparse column scheme, it should be at least n+1, It need not be set when the other schemes are used.
Ao_ptr	is a one-dimensional array of size Ao_ptr_ne and type INT, that holds the starting position of each row of $A_o$, as well as the total number of entries, in the sparse row-wise storage scheme. By contrast, it holds the starting position of each column of $A_o$, as well as the total number of entries, in the sparse column-wise storage scheme. It need not be set when the other schemes are used, and in this case can be C_NULL.

    function blls_import_without_a(T, INT, control, data, status, n, o)

Import problem data into internal storage prior to solution when $A_o$ is not explicitly available.

Parameters:

control	is a structure whose members provide control parameters for the remaining procedures (see blls_control_type)
data	holds private internal data
status	is a scalar variable of type INT that gives the exit status from the package. Possible values are: 1 The import was successful, and the package is ready for the solve phase -1 An allocation error occurred. A message indicating the offending array is written on unit control.error, and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -2 A deallocation error occurred. A message indicating the offending array is written on unit control.error and the returned allocation status and a string containing the name of the offending array are held in inform.alloc_status and inform.bad_alloc respectively. -3 The restriction n > 0 or m > 0 has been violated.
n	is a scalar variable of type INT that holds the number of variables.
o	is a scalar variable of type INT that holds the number of residuals.

    function blls_reset_control(T, INT, control, data, status)

Reset control parameters after import if required.

Parameters:

control

is a structure whose members provide control parameters for the remaining procedures (see blls_control_type)

data

holds private internal data

status

is a scalar variable of type INT that gives the exit status from the package. Possible values are:

1
The import was successful, and the package is ready for the solve phase

    function blls_solve_given_a(T, INT, data, userdata, status, n, o,
                                Ao_ne, Ao_val, b, sigma, x_l, x_u,
                                x, z, r, g, x_stat, w, x_s, eval_prec)

Solve the bound-constrained linear least-squares problem when the Jacobian $A$ is available.

Parameters:

    function blls_solve_reverse_a_prod(T, INT, data, status, eval_status,
                                       n, o, b, sigma, x_l, x_u,
                                       x, z, r, g, x_stat, v, p,
                                       nz_v, nz_v_start, nz_v_end, nz_p,
                                       nz_p_end, w, x_s)

Solve the bound-constrained linear least-squares problem when the products of the Jacobian $A$ and its transpose with specified vectors may be computed by the calling program.

Parameters:

    function blls_information(T, INT, data, inform, status)

Provides output information

Parameters:

data

holds private internal data

inform

is a structure containing output information (see blls_inform_type)

status

is a scalar variable of type INT that gives the exit status from the package. Possible values are (currently):

0
The values were recorded successfully

    function blls_terminate(T, INT, data, control, inform)

Deallocate all internal private storage

Parameters:

data	holds private internal data
control	is a structure containing control information (see blls_control_type)
inform	is a structure containing output information (see blls_inform_type)