aGrUM  0.13.2
gum::credal::lp::LpInterface< GUM_SCALAR > Class Template Reference

Class representing a linear program. More...

#include <agrum/CN/LpInterface.h>

+ Collaboration diagram for gum::credal::lp::LpInterface< GUM_SCALAR >:

Public Member Functions

LpCol addCol ()
 Insert a new column, i.e. More...
 
std::vector< LpColaddCols (const unsigned int &cols)
 Insert new columns, i.e. More...
 
void addRow (const LpExpr &expr)
 Add rows to the linear program according to a given expression ( which must be at least an inequality ). More...
 
void addRow (LpExpr &&expr)
 Add rows to the linear program according to a given expression ( which must be at least an inequality ). More...
 
void addPositivity ()
 Add positivity constraints for all variables. More...
 
void addSumIsOne ()
 Add sum of variables is 1 constraints. More...
 
void addProba ()
 Add positivity constraints and sum of variables is 1 ( probability constraints ) More...
 
std::vector< std::vector< GUM_SCALAR > > solve ()
 Solve the linear program (H-representation of the polytope) by enumeration (of the polytope vertices) using lexicographic reverse search (lrs). More...
 
std::vector< LpColgetCols () const
 Get the variables of the LP. More...
 
std::string toString () const
 Get the string representation of a calling linear program. More...
 
void clear ()
 Reset the rows (inequalities) and columns (variables) of the LP as if it was created. More...
 
void clearRows ()
 Reset the rows (inequalities) of the LP but not the columns (variables are kept). More...
 
Constructor / Destructor
 LpInterface ()
 Default constructor, empty problem. More...
 
 LpInterface (const LpInterface< GUM_SCALAR > &from)
 Copy constructor. More...
 
 LpInterface (LpInterface< GUM_SCALAR > &&from)
 Move copy constructor. More...
 
 ~LpInterface ()
 Default destructor. More...
 
Compound assignment operator
LpInterface< GUM_SCALAR > & operator= (const LpInterface< GUM_SCALAR > &from)
 Copy compound assignment. More...
 
LpInterface< GUM_SCALAR > & operator= (LpInterface< GUM_SCALAR > &&from)
 Move coumpound assignment. More...
 

Friends

template<typename T >
std::ostream & operator<< (std::ostream &out, const LpInterface< T > &lpi)
 Overload of << to use with output streams ( such as std::cout << ). More...
 

Detailed Description

template<typename GUM_SCALAR>
class gum::credal::lp::LpInterface< GUM_SCALAR >

Class representing a linear program.

Author
Matthieu HOURBRACQ and Pierre-Henri WUILLEMIN

Definition at line 47 of file LpInterface.h.

Constructor & Destructor Documentation

template<typename GUM_SCALAR >
gum::credal::lp::LpInterface< GUM_SCALAR >::LpInterface ( )

Default constructor, empty problem.

class LpInterface

Definition at line 754 of file LpInterface_tpl.h.

754  {
755  __positivity = false;
756  __sumIsOne = false;
757  GUM_CONSTRUCTOR(LpInterface);
758  }
LpInterface()
Default constructor, empty problem.
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
template<typename GUM_SCALAR >
gum::credal::lp::LpInterface< GUM_SCALAR >::LpInterface ( const LpInterface< GUM_SCALAR > &  from)

Copy constructor.

Parameters
fromThe LpInterface to be copied.

Definition at line 761 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__rows.

762  :
763  __cols(from.__cols),
764  __positivity(from.__positivity), __sumIsOne(from.__sumIsOne) {
765  __rows.resize(from.__rows.size());
766 
767  for (unsigned int i = 0, end = from.__rows.size(); i < end; i++)
768  __rows[i] = new LpRow(*from.__rows[i]);
769 
770  GUM_CONS_CPY(LpInterface);
771  }
LpInterface()
Default constructor, empty problem.
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
gum::credal::lp::LpInterface< GUM_SCALAR >::LpInterface ( LpInterface< GUM_SCALAR > &&  from)

Move copy constructor.

Parameters
fromThe temporary LpInterface to be moved.

Definition at line 774 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, and gum::credal::lp::LpInterface< GUM_SCALAR >::__rows.

774  :
775  __positivity(from.__positivity), __sumIsOne(from.__sumIsOne) {
776  __rows.swap(from.__rows);
777  __cols.swap(from.__cols);
778  GUM_CONS_CPY(LpInterface);
779  }
LpInterface()
Default constructor, empty problem.
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
gum::credal::lp::LpInterface< GUM_SCALAR >::~LpInterface ( )

Default destructor.

Definition at line 782 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and gum::credal::lp::LpInterface< GUM_SCALAR >::operator=().

782  {
783  for (const auto row : __rows)
784  delete row;
785 
786  GUM_DESTRUCTOR(LpInterface);
787  }
LpInterface()
Default constructor, empty problem.
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743

+ Here is the call graph for this function:

Member Function Documentation

template<typename GUM_SCALAR >
LpCol gum::credal::lp::LpInterface< GUM_SCALAR >::addCol ( )

Insert a new column, i.e.

a new variable.

Returns
A copy of the variable.

Definition at line 830 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols.

830  {
831  LpCol col((unsigned int)__cols.size());
832 
833  __cols.push_back(col);
834 
835  return col;
836  }
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
std::vector< LpCol > gum::credal::lp::LpInterface< GUM_SCALAR >::addCols ( const unsigned int &  cols)

Insert new columns, i.e.

new variables.

Parameters
colsthe constant reference to the number of variables we want.
Returns
The copy of the vector of all variables of the problem.

Definition at line 840 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, and GUM_ERROR.

840  {
841  if (cols < 1)
842  GUM_ERROR(OperationNotAllowed,
843  "LpInterface::addCols ( cols ) : cols "
844  "needs must be equal or greater than 1 : "
845  << cols << " < 1");
846 
847  for (unsigned int i = 0; i < cols; i++) {
848  __cols.push_back(LpCol((unsigned int)__cols.size()));
849  }
850 
851  return __cols;
852  }
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
#define GUM_ERROR(type, msg)
Definition: exceptions.h:66
template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::addPositivity ( )

Add positivity constraints for all variables.

Definition at line 907 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, and gum::credal::lp::LpInterface< GUM_SCALAR >::addRow().

Referenced by gum::credal::lp::LpInterface< GUM_SCALAR >::addProba().

907  {
908  if (__positivity) return;
909 
910  for (const auto& col : __cols)
911  addRow(0 <= col);
912 
913  __positivity = true;
914  }
void addRow(const LpExpr &expr)
Add rows to the linear program according to a given expression ( which must be at least an inequality...
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::addProba ( )

Add positivity constraints and sum of variables is 1 ( probability constraints )

Definition at line 931 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne, gum::credal::lp::LpInterface< GUM_SCALAR >::addPositivity(), gum::credal::lp::LpInterface< GUM_SCALAR >::addRow(), and gum::credal::lp::LpInterface< GUM_SCALAR >::addSumIsOne().

931  {
932  if (__positivity && __sumIsOne) {
933  return;
934  } else if (__positivity && !__sumIsOne) {
935  addSumIsOne();
936  return;
937  } else if (!__positivity && __sumIsOne) {
938  addPositivity();
939  return;
940  }
941 
942  // we can do both with one loop, don't call the above functions.
943  // addPositivity();
944  // addSumIsOne();
945  LpExpr expr;
946 
947  for (const auto& col : __cols) {
948  addRow(0 <= col);
949  expr += col;
950  }
951 
952  addRow(1 <= std::move(expr) <= 1);
953 
954  __sumIsOne = true;
955  __positivity = true;
956  }
void addRow(const LpExpr &expr)
Add rows to the linear program according to a given expression ( which must be at least an inequality...
void addPositivity()
Add positivity constraints for all variables.
void addSumIsOne()
Add sum of variables is 1 constraints.
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

+ Here is the call graph for this function:

template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::addRow ( const LpExpr expr)

Add rows to the linear program according to a given expression ( which must be at least an inequality ).

Parameters
exprthe constant reference to the expression to convert to rows.

Definition at line 855 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpExpr::__ileft, gum::credal::lp::LpExpr::__iright, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, GUM_ERROR, and gum::credal::lp::LpExpr::toString().

Referenced by gum::credal::lp::LpInterface< GUM_SCALAR >::addPositivity(), gum::credal::lp::LpInterface< GUM_SCALAR >::addProba(), and gum::credal::lp::LpInterface< GUM_SCALAR >::addSumIsOne().

855  {
856  if (!expr.__ileft && !expr.__iright)
857  GUM_ERROR(OperationNotAllowed,
858  "addRow ( const LpExpr & expr ) : expr : "
859  << expr.toString() << "is not an inequality.");
860 
861  if ((expr.__ileft && !expr.__iright) || (!expr.__ileft && expr.__iright)) {
862  __rows.push_back(new LpRow(expr, __cols));
863  } else {
864  LpExpr lexpr(expr, true, true, false);
865  LpExpr rexpr(expr, false, true, true);
866 
867  __rows.push_back(
868  new LpRow(std::move(lexpr),
869  __cols));
870  __rows.push_back(
871  new LpRow(std::move(rexpr),
872  __cols));
873  }
874  }
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
#define GUM_ERROR(type, msg)
Definition: exceptions.h:66

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::addRow ( LpExpr &&  expr)

Add rows to the linear program according to a given expression ( which must be at least an inequality ).

Parameters
exprthe temporary expression to move to rows.

Definition at line 877 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpExpr::__imiddle, gum::credal::lp::LpExpr::__mCoeffs, gum::credal::lp::LpExpr::__mValue, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and GUM_ERROR.

877  {
878  if (!expr.__ileft && !expr.__iright)
879  GUM_ERROR(OperationNotAllowed,
880  "addRow ( const LpExpr & expr ) : expr : "
881  << expr.toString() << "is not an inequality.");
882 
883  if ((expr.__ileft && !expr.__iright) || (!expr.__ileft && expr.__iright)) {
884  __rows.push_back(new LpRow(std::move(expr), __cols));
885  } else {
886  LpExpr lexpr(std::move(expr), true, true, false);
887 
889  LpExpr rexpr(std::move(expr), false, false, true);
890 
892 
893  *rexpr.__mCoeffs = *lexpr.__mCoeffs;
894  rexpr.__mValue = lexpr.__mValue;
895  rexpr.__imiddle = true;
896 
897  __rows.push_back(
898  new LpRow(std::move(lexpr),
899  __cols));
900  __rows.push_back(
901  new LpRow(std::move(rexpr),
902  __cols));
903  }
904  }
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
#define GUM_ERROR(type, msg)
Definition: exceptions.h:66
template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::addSumIsOne ( )

Add sum of variables is 1 constraints.

Definition at line 917 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne, and gum::credal::lp::LpInterface< GUM_SCALAR >::addRow().

Referenced by gum::credal::lp::LpInterface< GUM_SCALAR >::addProba().

917  {
918  if (__sumIsOne) return;
919 
920  LpExpr expr;
921 
922  for (const auto& col : __cols)
923  expr += col;
924 
925  addRow(1 <= std::move(expr) <= 1);
926 
927  __sumIsOne = true;
928  }
void addRow(const LpExpr &expr)
Add rows to the linear program according to a given expression ( which must be at least an inequality...
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::clear ( )

Reset the rows (inequalities) and columns (variables) of the LP as if it was created.

Definition at line 1009 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne.

1009  {
1010  for (const auto& row : __rows)
1011  delete row;
1012 
1013  __rows.clear();
1014  __rows.shrink_to_fit();
1015 
1019  __cols.clear();
1020  __cols.shrink_to_fit();
1021 
1022  __positivity = false;
1023  __sumIsOne = false;
1024  }
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
void gum::credal::lp::LpInterface< GUM_SCALAR >::clearRows ( )

Reset the rows (inequalities) of the LP but not the columns (variables are kept).

Definition at line 1027 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne.

1027  {
1028  for (const auto& row : __rows)
1029  delete row;
1030 
1031  __rows.clear();
1032  __rows.shrink_to_fit();
1033 
1034  __positivity = false;
1035  __sumIsOne = false;
1036  }
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
template<typename GUM_SCALAR >
std::vector< LpCol > gum::credal::lp::LpInterface< GUM_SCALAR >::getCols ( ) const

Get the variables of the LP.

Returns
A copy of the variables as a vector of variables.

Definition at line 985 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols.

985  {
986  return __cols;
987  }
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
LpInterface< GUM_SCALAR > & gum::credal::lp::LpInterface< GUM_SCALAR >::operator= ( const LpInterface< GUM_SCALAR > &  from)

Copy compound assignment.

Parameters
fromThe LpInterface to be copied.

Definition at line 791 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne.

Referenced by gum::credal::lp::LpInterface< GUM_SCALAR >::~LpInterface().

791  {
793  for (const auto& row : __rows)
794  delete row;
795 
796  __rows.clear();
797  __rows.shrink_to_fit();
798 
799  __rows.resize(from.__rows.size());
800 
801  for (unsigned int i = 0, end = from.__rows.size(); i < end; i++)
802  __rows[i] = new LpRow(*from.__rows[i]);
803 
804  __cols = from.__cols;
805  __positivity = from.__positivity;
806  __sumIsOne = from.__sumIsOne;
807 
808  return *this;
809  }
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

+ Here is the caller graph for this function:

template<typename GUM_SCALAR >
LpInterface< GUM_SCALAR > & gum::credal::lp::LpInterface< GUM_SCALAR >::operator= ( LpInterface< GUM_SCALAR > &&  from)

Move coumpound assignment.

Parameters
fromThe temporary LpInterface to be moved.

Definition at line 813 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__positivity, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, and gum::credal::lp::LpInterface< GUM_SCALAR >::__sumIsOne.

813  {
814  __rows.swap(from.__rows);
815  __cols.swap(from.__cols);
816 
817  __positivity = from.__positivity;
818  __sumIsOne = from.__sumIsOne;
819 
820  return *this;
821  }
bool __sumIsOne
true if addSumIsOne() has been called, false otherwise.
Definition: LpInterface.h:752
bool __positivity
true if addPositivity() has been called, false otherwise.
Definition: LpInterface.h:749
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745
template<typename GUM_SCALAR >
std::vector< std::vector< GUM_SCALAR > > gum::credal::lp::LpInterface< GUM_SCALAR >::solve ( )

Solve the linear program (H-representation of the polytope) by enumeration (of the polytope vertices) using lexicographic reverse search (lrs).

Only works with bounded polyhedron (polytopes) and not unbounded ones (i.e. defined by vertices and rays).

Returns
The V-representation (vertices) of the polytope as a vector of vectors (vector of vertices).

Definition at line 959 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, gum::credal::lp::LpInterface< GUM_SCALAR >::__rows, gum::credal::LRSWrapper< GUM_SCALAR >::fillMatrix(), gum::credal::LRSWrapper< GUM_SCALAR >::getOutput(), gum::credal::LRSWrapper< GUM_SCALAR >::H2V(), and gum::credal::LRSWrapper< GUM_SCALAR >::setUpH().

959  {
960  LRSWrapper< GUM_SCALAR > lrs;
961 
962  lrs.setUpH((unsigned int)__cols.size());
963 
964  std::vector< std::vector< GUM_SCALAR > > lrsMatrix;
965 
966  for (const auto& row : __rows) {
967  std::vector< GUM_SCALAR > expandedRow(__cols.size() + 1, 0);
968 
969  expandedRow[0] = row->__cste;
970 
971  for (const auto& elt : *row->__coeffs)
972  expandedRow[elt.first.id() + 1] = elt.second;
973 
974  lrsMatrix.push_back(expandedRow);
975  }
976 
977  lrs.fillMatrix(lrsMatrix);
978 
979  lrs.H2V();
980 
981  return lrs.getOutput();
982  }
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

+ Here is the call graph for this function:

template<typename GUM_SCALAR >
std::string gum::credal::lp::LpInterface< GUM_SCALAR >::toString ( ) const

Get the string representation of a calling linear program.

Returns
The string representation of the calling linear program.

Definition at line 990 of file LpInterface_tpl.h.

References gum::credal::lp::LpInterface< GUM_SCALAR >::__cols, and gum::credal::lp::LpInterface< GUM_SCALAR >::__rows.

990  {
991  std::ostringstream s;
992 
993  s << std::endl << std::endl << "Variables : " << std::endl;
994 
995  for (const auto& col : __cols)
996  s << " " << col.toString();
997 
998  s << std::endl;
999 
1000  for (const auto& row : __rows)
1001  s << std::endl << row->toString();
1002 
1003  s << std::endl << std::endl;
1004 
1005  return s.str();
1006  }
std::vector< LpRow * > __rows
Rows of the problem.
Definition: LpInterface.h:743
std::vector< LpCol > __cols
Variables of the problem.
Definition: LpInterface.h:745

Friends And Related Function Documentation

template<typename GUM_SCALAR>
template<typename T >
std::ostream& operator<< ( std::ostream &  out,
const LpInterface< T > &  lpi 
)
friend

Overload of << to use with output streams ( such as std::cout << ).

Parameters
outthe reference to the caller, i.e. left side of <<.
lpithe constant reference to the linear program whose representation we want.
Returns
The address of the caller.

Definition at line 824 of file LpInterface_tpl.h.

824  {
825  out << lpi.toString();
826  return out;
827  }

Member Data Documentation


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