alpaqa 1.0.0a8
Nonconvex constrained optimization
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Private Types | Private Member Functions | Private Attributes | List of all members
DLProblem Class Reference

#include <interop/dl/include/alpaqa/dl/dl-problem.hpp>

Detailed Description

Class that loads a problem using dlopen.

The shared library should export a C function with the name <symbol_prefix>_register that accepts a void pointer with user data, and returns a struct of type alpaqa_problem_register_t that contains all data to represent the problem, as well as function pointers for all required operations. See C++/DLProblem/main.cpp

Note
Copies are shallow, they all share the same problem instance, take that into account when using multiple threads.
See also
TypeErasedProblem
Examples
C++/DLProblem/main.cpp.

Definition at line 107 of file dl-problem.hpp.

+ Inheritance diagram for DLProblem:
+ Collaboration diagram for DLProblem:

Public Types

using instance_t = DLLoader::instance_t
 
using Box = alpaqa::Box< config_t >
 

Public Member Functions

 DLProblem (std::string so_filename, std::string symbol_prefix="alpaqa_problem", void *user_param=nullptr)
 Load a problem from a shared library.
 
real_t eval_prox_grad_step (real_t γ, crvec x, crvec grad_ψ, rvec x̂, rvec p) const
 
real_t eval_f (crvec x) const
 
void eval_grad_f (crvec x, rvec grad_fx) const
 
void eval_g (crvec x, rvec gx) const
 
void eval_grad_g_prod (crvec x, crvec y, rvec grad_gxy) const
 
void eval_jac_g (crvec x, rindexvec inner_idx, rindexvec outer_ptr, rvec J_values) const
 
length_t get_jac_g_num_nonzeros () const
 
void eval_grad_gi (crvec x, index_t i, rvec grad_gi) const
 
void eval_hess_L_prod (crvec x, crvec y, real_t scale, crvec v, rvec Hv) const
 
void eval_hess_L (crvec x, crvec y, real_t scale, rindexvec inner_idx, rindexvec outer_ptr, rvec H_values) const
 
length_t get_hess_L_num_nonzeros () const
 
void eval_hess_ψ_prod (crvec x, crvec y, crvec Σ, real_t scale, crvec v, rvec Hv) const
 
void eval_hess_ψ (crvec x, crvec y, crvec Σ, real_t scale, rindexvec inner_idx, rindexvec outer_ptr, rvec H_values) const
 
length_t get_hess_ψ_num_nonzeros () const
 
real_t eval_f_grad_f (crvec x, rvec grad_fx) const
 
real_t eval_f_g (crvec x, rvec g) const
 
void eval_grad_f_grad_g_prod (crvec x, crvec y, rvec grad_f, rvec grad_gxy) const
 
void eval_grad_L (crvec x, crvec y, rvec grad_L, rvec work_n) const
 
real_t eval_ψ (crvec x, crvec y, crvec Σ, rvec ŷ) const
 
void eval_grad_ψ (crvec x, crvec y, crvec Σ, rvec grad_ψ, rvec work_n, rvec work_m) const
 
real_t eval_ψ_grad_ψ (crvec x, crvec y, crvec Σ, rvec grad_ψ, rvec work_n, rvec work_m) const
 
bool provides_eval_f () const
 
bool provides_eval_grad_f () const
 
bool provides_eval_g () const
 
bool provides_eval_grad_g_prod () const
 
bool provides_eval_jac_g () const
 
bool provides_get_jac_g_num_nonzeros () const
 
bool provides_eval_grad_gi () const
 
bool provides_eval_hess_L_prod () const
 
bool provides_eval_hess_L () const
 
bool provides_get_hess_L_num_nonzeros () const
 
bool provides_eval_hess_ψ_prod () const
 
bool provides_eval_hess_ψ () const
 
bool provides_get_hess_ψ_num_nonzeros () const
 
bool provides_eval_f_grad_f () const
 
bool provides_eval_f_g () const
 
bool provides_eval_grad_f_grad_g_prod () const
 
bool provides_eval_grad_L () const
 
bool provides_eval_ψ () const
 
bool provides_eval_grad_ψ () const
 
bool provides_eval_ψ_grad_ψ () const
 
bool provides_get_box_C () const
 
template<class Signature , class... Args>
decltype(auto) call_extra_func (const std::string &name, Args &&...args) const
 
template<class Signature , class... Args>
decltype(auto) call_extra_func (const std::string &name, Args &&...args)
 
void resize (length_t n, length_t m)
 
length_t get_n () const
 Number of decision variables, n.
 
length_t get_m () const
 Number of constraints, m.
 
void eval_proj_diff_g (crvec z, rvec p) const
 
void eval_proj_multipliers (rvec y, real_t M) const
 
const Boxget_box_C () const
 
const Boxget_box_D () const
 
index_t eval_inactive_indices_res_lna (real_t γ, crvec x, crvec grad_ψ, rindexvec J) const
 
void check () const
 

Static Public Member Functions

static real_t eval_proj_grad_step_box (const Box &C, real_t γ, crvec x, crvec grad_ψ, rvec x̂, rvec p)
 Projected gradient step for rectangular box C.
 
static void eval_prox_grad_step_box_l1_impl (const Box &C, const auto &λ, real_t γ, crvec x, crvec grad_ψ, rvec x̂, rvec p)
 Proximal gradient step for rectangular box C with ℓ₁-regularization.
 
static real_t eval_prox_grad_step_box_l1 (const Box &C, const auto &λ, real_t γ, crvec x, crvec grad_ψ, rvec x̂, rvec p)
 Proximal gradient step for rectangular box C with ℓ₁-regularization.
 
static real_t eval_prox_grad_step_box_l1_scal (const Box &C, real_t λ, real_t γ, crvec x, crvec grad_ψ, rvec x̂, rvec p)
 Proximal gradient step for rectangular box C with ℓ₁-regularization.
 
static void eval_proj_multipliers_box (const Box &D, rvec y, real_t M, index_t penalty_alm_split)
 

Public Attributes

length_t n
 Number of decision variables, dimension of x.
 
length_t m
 Number of constraints, dimension of g(x) and z.
 
index_t penalty_alm_split
 Components of the constraint function with indices below this number are handled using a quadratic penalty method rather than using an augmented Lagrangian method.
 
Box C
 Constraints of the decision variables, \( x \in C \).
 
Box D
 Other constraints, \( g(x) \in D \).
 
vec l1_reg
 \( \ell_1 \) (1-norm) regularization parameter.
 

Private Types

using dl_handle_t = std::shared_ptr< void >
 

Private Member Functions

std::shared_ptr< void > load_lib () const
 Open the shared library using dlopen
 
template<class F >
F * load_func (std::string_view name) const
 Load a function with signature F from the library using dlsym.
 
template<class Signature >
requires std::is_function_v<Signature>
const std::function< Signature > & extra_func (const std::string &name) const
 
template<class Ret , class... FArgs, class... Args>
decltype(auto) call_extra_func_helper (const void *instance, FuncTag< Ret(const instance_t *, FArgs...)>, const std::string &name, Args &&...args) const
 
template<class Ret , class... FArgs, class... Args>
decltype(auto) call_extra_func_helper (void *instance, FuncTag< Ret(instance_t *, FArgs...)>, const std::string &name, Args &&...args)
 
template<class Ret , class... FArgs, class... Args>
decltype(auto) call_extra_func_helper (const void *, FuncTag< Ret(FArgs...)>, const std::string &name, Args &&...args) const
 

Private Attributes

std::shared_ptr< void > instance
 Problem instance created by the registration function, including the deleter to destroy it.
 
problem_functions_tfunctions = nullptr
 Pointer to the struct of function pointers for evaluating the objective, constraints, their gradients, etc.
 
std::string so_filename
 
std::string symbol_prefix
 
dl_handle_t handle
 Handle to the shared library (returned by dlopen).
 
std::shared_ptr< function_dict_textra_functions
 An associative array of additional functions exposed by the problem.
 

Member Typedef Documentation

◆ instance_t

using instance_t = DLLoader::instance_t

Definition at line 175 of file dl-problem.hpp.

◆ dl_handle_t

using dl_handle_t = std::shared_ptr<void>
protectedinherited

Definition at line 29 of file dl-problem.hpp.

◆ Box

using Box = alpaqa::Box<config_t>
inherited

Definition at line 16 of file box-constr-problem.hpp.

Constructor & Destructor Documentation

◆ DLProblem()

DLProblem ( std::string  so_filename,
std::string  symbol_prefix = "alpaqa_problem",
void *  user_param = nullptr 
)

Load a problem from a shared library.

Parameters
so_filenameFilename of the shared library to load.
symbol_prefixPrefix of the registration function.
user_paramPointer to custom user data to pass to the registration function.

Definition at line 37 of file dl-problem.cpp.

Member Function Documentation

◆ eval_prox_grad_step()

auto eval_prox_grad_step ( real_t  γ,
crvec  x,
crvec  grad_ψ,
rvec  ,
rvec  p 
) const

Definition at line 90 of file dl-problem.cpp.

+ Here is the call graph for this function:

◆ eval_f()

auto eval_f ( crvec  x) const

Definition at line 99 of file dl-problem.cpp.

◆ eval_grad_f()

auto eval_grad_f ( crvec  x,
rvec  grad_fx 
) const

Definition at line 100 of file dl-problem.cpp.

◆ eval_g()

auto eval_g ( crvec  x,
rvec  gx 
) const

Definition at line 101 of file dl-problem.cpp.

◆ eval_grad_g_prod()

auto eval_grad_g_prod ( crvec  x,
crvec  y,
rvec  grad_gxy 
) const

Definition at line 102 of file dl-problem.cpp.

◆ eval_jac_g()

auto eval_jac_g ( crvec  x,
rindexvec  inner_idx,
rindexvec  outer_ptr,
rvec  J_values 
) const

Definition at line 104 of file dl-problem.cpp.

◆ get_jac_g_num_nonzeros()

auto get_jac_g_num_nonzeros ( ) const

Definition at line 105 of file dl-problem.cpp.

◆ eval_grad_gi()

auto eval_grad_gi ( crvec  x,
index_t  i,
rvec  grad_gi 
) const

Definition at line 103 of file dl-problem.cpp.

◆ eval_hess_L_prod()

auto eval_hess_L_prod ( crvec  x,
crvec  y,
real_t  scale,
crvec  v,
rvec  Hv 
) const

Definition at line 106 of file dl-problem.cpp.

◆ eval_hess_L()

auto eval_hess_L ( crvec  x,
crvec  y,
real_t  scale,
rindexvec  inner_idx,
rindexvec  outer_ptr,
rvec  H_values 
) const

Definition at line 107 of file dl-problem.cpp.

◆ get_hess_L_num_nonzeros()

auto get_hess_L_num_nonzeros ( ) const

Definition at line 108 of file dl-problem.cpp.

◆ eval_hess_ψ_prod()

auto eval_hess_ψ_prod ( crvec  x,
crvec  y,
crvec  Σ,
real_t  scale,
crvec  v,
rvec  Hv 
) const

Definition at line 109 of file dl-problem.cpp.

◆ eval_hess_ψ()

auto eval_hess_ψ ( crvec  x,
crvec  y,
crvec  Σ,
real_t  scale,
rindexvec  inner_idx,
rindexvec  outer_ptr,
rvec  H_values 
) const

Definition at line 110 of file dl-problem.cpp.

◆ get_hess_ψ_num_nonzeros()

auto get_hess_ψ_num_nonzeros ( ) const

Definition at line 111 of file dl-problem.cpp.

◆ eval_f_grad_f()

auto eval_f_grad_f ( crvec  x,
rvec  grad_fx 
) const

Definition at line 112 of file dl-problem.cpp.

◆ eval_f_g()

auto eval_f_g ( crvec  x,
rvec  g 
) const

Definition at line 113 of file dl-problem.cpp.

◆ eval_grad_f_grad_g_prod()

auto eval_grad_f_grad_g_prod ( crvec  x,
crvec  y,
rvec  grad_f,
rvec  grad_gxy 
) const

Definition at line 114 of file dl-problem.cpp.

◆ eval_grad_L()

auto eval_grad_L ( crvec  x,
crvec  y,
rvec  grad_L,
rvec  work_n 
) const

Definition at line 115 of file dl-problem.cpp.

◆ eval_ψ()

auto eval_ψ ( crvec  x,
crvec  y,
crvec  Σ,
rvec  ŷ 
) const

Definition at line 116 of file dl-problem.cpp.

◆ eval_grad_ψ()

auto eval_grad_ψ ( crvec  x,
crvec  y,
crvec  Σ,
rvec  grad_ψ,
rvec  work_n,
rvec  work_m 
) const

Definition at line 117 of file dl-problem.cpp.

◆ eval_ψ_grad_ψ()

auto eval_ψ_grad_ψ ( crvec  x,
crvec  y,
crvec  Σ,
rvec  grad_ψ,
rvec  work_n,
rvec  work_m 
) const

Definition at line 118 of file dl-problem.cpp.

◆ provides_eval_f()

bool provides_eval_f ( ) const

Definition at line 120 of file dl-problem.cpp.

◆ provides_eval_grad_f()

bool provides_eval_grad_f ( ) const

Definition at line 121 of file dl-problem.cpp.

◆ provides_eval_g()

bool provides_eval_g ( ) const

Definition at line 122 of file dl-problem.cpp.

◆ provides_eval_grad_g_prod()

bool provides_eval_grad_g_prod ( ) const

Definition at line 123 of file dl-problem.cpp.

◆ provides_eval_jac_g()

bool provides_eval_jac_g ( ) const

Definition at line 124 of file dl-problem.cpp.

◆ provides_get_jac_g_num_nonzeros()

bool provides_get_jac_g_num_nonzeros ( ) const

Definition at line 125 of file dl-problem.cpp.

◆ provides_eval_grad_gi()

bool provides_eval_grad_gi ( ) const

Definition at line 126 of file dl-problem.cpp.

◆ provides_eval_hess_L_prod()

bool provides_eval_hess_L_prod ( ) const

Definition at line 127 of file dl-problem.cpp.

◆ provides_eval_hess_L()

bool provides_eval_hess_L ( ) const

Definition at line 128 of file dl-problem.cpp.

◆ provides_get_hess_L_num_nonzeros()

bool provides_get_hess_L_num_nonzeros ( ) const

Definition at line 129 of file dl-problem.cpp.

◆ provides_eval_hess_ψ_prod()

bool provides_eval_hess_ψ_prod ( ) const

Definition at line 130 of file dl-problem.cpp.

◆ provides_eval_hess_ψ()

bool provides_eval_hess_ψ ( ) const

Definition at line 131 of file dl-problem.cpp.

◆ provides_get_hess_ψ_num_nonzeros()

bool provides_get_hess_ψ_num_nonzeros ( ) const

Definition at line 132 of file dl-problem.cpp.

◆ provides_eval_f_grad_f()

bool provides_eval_f_grad_f ( ) const

Definition at line 133 of file dl-problem.cpp.

◆ provides_eval_f_g()

bool provides_eval_f_g ( ) const

Definition at line 134 of file dl-problem.cpp.

◆ provides_eval_grad_f_grad_g_prod()

bool provides_eval_grad_f_grad_g_prod ( ) const

Definition at line 135 of file dl-problem.cpp.

◆ provides_eval_grad_L()

bool provides_eval_grad_L ( ) const

Definition at line 136 of file dl-problem.cpp.

◆ provides_eval_ψ()

bool provides_eval_ψ ( ) const

Definition at line 137 of file dl-problem.cpp.

◆ provides_eval_grad_ψ()

bool provides_eval_grad_ψ ( ) const

Definition at line 138 of file dl-problem.cpp.

◆ provides_eval_ψ_grad_ψ()

bool provides_eval_ψ_grad_ψ ( ) const

Definition at line 139 of file dl-problem.cpp.

◆ provides_get_box_C()

bool provides_get_box_C ( ) const

Definition at line 140 of file dl-problem.cpp.

◆ call_extra_func() [1/2]

decltype(auto) call_extra_func ( const std::string &  name,
Args &&...  args 
) const
inline

Definition at line 178 of file dl-problem.hpp.

◆ call_extra_func() [2/2]

decltype(auto) call_extra_func ( const std::string &  name,
Args &&...  args 
)
inline

Definition at line 185 of file dl-problem.hpp.

+ Here is the call graph for this function:

◆ load_lib()

std::shared_ptr< void > load_lib ( ) const
protectedinherited

Open the shared library using dlopen

Definition at line 12 of file dl-problem.cpp.

◆ load_func()

F * load_func ( std::string_view  name) const
protectedinherited

Load a function with signature F from the library using dlsym.

Definition at line 22 of file dl-problem.cpp.

◆ extra_func()

const std::function< Signature > & extra_func ( const std::string &  name) const
inlineprotectedinherited

Definition at line 44 of file dl-problem.hpp.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ call_extra_func_helper() [1/3]

decltype(auto) call_extra_func_helper ( const void *  instance,
FuncTag< Ret(const instance_t *, FArgs...)>  ,
const std::string &  name,
Args &&...  args 
) const
inlineprotectedinherited

Definition at line 71 of file dl-problem.hpp.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ call_extra_func_helper() [2/3]

decltype(auto) call_extra_func_helper ( void *  instance,
FuncTag< Ret(instance_t *, FArgs...)>  ,
const std::string &  name,
Args &&...  args 
)
inlineprotectedinherited

Definition at line 80 of file dl-problem.hpp.

+ Here is the call graph for this function:

◆ call_extra_func_helper() [3/3]

decltype(auto) call_extra_func_helper ( const void *  ,
FuncTag< Ret(FArgs...)>  ,
const std::string &  name,
Args &&...  args 
) const
inlineprotectedinherited

Definition at line 87 of file dl-problem.hpp.

+ Here is the call graph for this function:

◆ resize()

void resize ( length_t  n,
length_t  m 
)
inlineinherited

Definition at line 37 of file box-constr-problem.hpp.

◆ get_n()

length_t get_n ( ) const
inlineinherited

Number of decision variables, n.

Definition at line 60 of file box-constr-problem.hpp.

◆ get_m()

length_t get_m ( ) const
inlineinherited

Number of constraints, m.

Definition at line 62 of file box-constr-problem.hpp.

◆ eval_proj_grad_step_box()

static real_t eval_proj_grad_step_box ( const Box C,
real_t  γ,
crvec  x,
crvec  grad_ψ,
rvec  ,
rvec  p 
)
inlinestaticinherited

Projected gradient step for rectangular box C.

\[ \begin{aligned} \hat x &= \Pi_C(x - \gamma\nabla\psi(x)) \\ p &= \hat x - x \\ &= \max(\underline x - x, \;\min(-\gamma\nabla\psi(x), \overline x - x) \end{aligned} \]

Definition at line 69 of file box-constr-problem.hpp.

◆ eval_prox_grad_step_box_l1_impl()

static void eval_prox_grad_step_box_l1_impl ( const Box C,
const auto &  λ,
real_t  γ,
crvec  x,
crvec  grad_ψ,
rvec  ,
rvec  p 
)
inlinestaticinherited

Proximal gradient step for rectangular box C with ℓ₁-regularization.

\[ \begin{aligned} h(x) &= \|x\|_1 + \delta_C(x) \\ \hat x &= \prox_{\gamma h}(x - \gamma\nabla\psi(x)) \\ &= -\max\big( x - \overline x, \;\min\big( x - \underline x, \;\min\big( \gamma(\nabla\psi(x) + \lambda), \;\max\big( \gamma(\nabla\psi(x) - \lambda), x \big) \big) \big) \big) \end{aligned} \]

Definition at line 92 of file box-constr-problem.hpp.

◆ eval_prox_grad_step_box_l1()

static real_t eval_prox_grad_step_box_l1 ( const Box C,
const auto &  λ,
real_t  γ,
crvec  x,
crvec  grad_ψ,
rvec  ,
rvec  p 
)
inlinestaticinherited

Proximal gradient step for rectangular box C with ℓ₁-regularization.

\[ \begin{aligned} h(x) &= \|x\|_1 + \delta_C(x) \\ \hat x &= \prox_{\gamma h}(x - \gamma\nabla\psi(x)) \\ &= -\max\big( x - \overline x, \;\min\big( x - \underline x, \;\min\big( \gamma(\nabla\psi(x) + \lambda), \;\max\big( \gamma(\nabla\psi(x) - \lambda), x \big) \big) \big) \big) \end{aligned} \]

Definition at line 101 of file box-constr-problem.hpp.

◆ eval_prox_grad_step_box_l1_scal()

static real_t eval_prox_grad_step_box_l1_scal ( const Box C,
real_t  λ,
real_t  γ,
crvec  x,
crvec  grad_ψ,
rvec  ,
rvec  p 
)
inlinestaticinherited

Proximal gradient step for rectangular box C with ℓ₁-regularization.

\[ \begin{aligned} h(x) &= \|x\|_1 + \delta_C(x) \\ \hat x &= \prox_{\gamma h}(x - \gamma\nabla\psi(x)) \\ &= -\max\big( x - \overline x, \;\min\big( x - \underline x, \;\min\big( \gamma(\nabla\psi(x) + \lambda), \;\max\big( \gamma(\nabla\psi(x) - \lambda), x \big) \big) \big) \big) \end{aligned} \]

Definition at line 108 of file box-constr-problem.hpp.

◆ eval_proj_diff_g()

void eval_proj_diff_g ( crvec  z,
rvec  p 
) const
inlineinherited
See also
TypeErasedProblem::eval_proj_diff_g

Definition at line 127 of file box-constr-problem.hpp.

◆ eval_proj_multipliers_box()

static void eval_proj_multipliers_box ( const Box D,
rvec  y,
real_t  M,
index_t  penalty_alm_split 
)
inlinestaticinherited

Definition at line 129 of file box-constr-problem.hpp.

◆ eval_proj_multipliers()

void eval_proj_multipliers ( rvec  y,
real_t  M 
) const
inlineinherited

◆ get_box_C()

const Box & get_box_C ( ) const
inlineinherited
See also
TypeErasedProblem::get_box_C

Definition at line 156 of file box-constr-problem.hpp.

◆ get_box_D()

const Box & get_box_D ( ) const
inlineinherited
See also
TypeErasedProblem::get_box_D

Definition at line 158 of file box-constr-problem.hpp.

◆ eval_inactive_indices_res_lna()

index_t eval_inactive_indices_res_lna ( real_t  γ,
crvec  x,
crvec  grad_ψ,
rindexvec  J 
) const
inlineinherited

◆ check()

void check ( ) const
inlineinherited
See also
TypeErasedProblem::check

Definition at line 198 of file box-constr-problem.hpp.

Member Data Documentation

◆ instance

std::shared_ptr<void> instance
private

Problem instance created by the registration function, including the deleter to destroy it.

Definition at line 123 of file dl-problem.hpp.

◆ functions

problem_functions_t* functions = nullptr
private

Pointer to the struct of function pointers for evaluating the objective, constraints, their gradients, etc.

Definition at line 126 of file dl-problem.hpp.

◆ so_filename

std::string so_filename
protectedinherited

Definition at line 26 of file dl-problem.hpp.

◆ symbol_prefix

std::string symbol_prefix
protectedinherited

Definition at line 27 of file dl-problem.hpp.

◆ handle

dl_handle_t handle
protectedinherited

Handle to the shared library (returned by dlopen).

Definition at line 31 of file dl-problem.hpp.

◆ extra_functions

std::shared_ptr<function_dict_t> extra_functions
protectedinherited

An associative array of additional functions exposed by the problem.

Definition at line 34 of file dl-problem.hpp.

◆ n

length_t n
inherited

Number of decision variables, dimension of x.

Definition at line 19 of file box-constr-problem.hpp.

◆ m

length_t m
inherited

Number of constraints, dimension of g(x) and z.

Definition at line 21 of file box-constr-problem.hpp.

◆ penalty_alm_split

index_t penalty_alm_split
inherited

Components of the constraint function with indices below this number are handled using a quadratic penalty method rather than using an augmented Lagrangian method.

Specifically, the Lagrange multipliers for these components (which determine the shifts in ALM) are kept at zero.

Definition at line 27 of file box-constr-problem.hpp.

◆ C

Box C
inherited

Constraints of the decision variables, \( x \in C \).

Definition at line 50 of file box-constr-problem.hpp.

◆ D

Box D
inherited

Other constraints, \( g(x) \in D \).

Definition at line 52 of file box-constr-problem.hpp.

◆ l1_reg

vec l1_reg
inherited

\( \ell_1 \) (1-norm) regularization parameter.

Possible dimensions are: \( 0 \) (no regularization), \( 1 \) (a single scalar factor), or \( n \) (a different factor for each variable).

Definition at line 57 of file box-constr-problem.hpp.


The documentation for this class was generated from the following files: