class for collecting and organizing a sequence of changes to block diagonal symmetric affine matrix functions so that it can be carried out in one step later on; More...

#include <PSCAffineModification.hxx>

Inheritance diagram for ConicBundle::PSCAffineModification:

Public Member Functions
Constructors and initialization
virtual	~PSCAffineModification ()

	PSCAffineModification (CH_Matrix_Classes::Integer var_olddim, const CH_Matrix_Classes::Indexmatrix &block_olddim, const CBout *cb=0, int incr=0)
	calls clear() with these parameters

int	clear (CH_Matrix_Classes::Integer var_olddim, const CH_Matrix_Classes::Indexmatrix &block_olddim)
	resets all variables so that the object to be modified has starting size var_olddim (number of variables) and block_olddim (number of rows) and no modifications More...

Routines for adding modifications
int	add_append_vars (CH_Matrix_Classes::Integer append_dim, const SparseCoeffmatMatrix *append_cols)
	append information on new variables at the respective ends More...

int	add_reassign_vars (const CH_Matrix_Classes::Indexmatrix &map_to_old)
	reassign the current variable indices (with modifications) as specified by map_to_old More...

int	add_delete_vars (const CH_Matrix_Classes::Indexmatrix &del_ind, CH_Matrix_Classes::Indexmatrix &map_to_old)
	delete the variables indexed by the vector del_ind and return the index changes of the others in a vector map_to_old More...

int	add_append_blocks (const CH_Matrix_Classes::Indexmatrix &append_dim, const SparseCoeffmatMatrix append_offsets, const SparseCoeffmatMatrix append_blocks)
	append information on new rows at the respective ends More...

int	add_reassign_blocks (const CH_Matrix_Classes::Indexmatrix &map_to_old)
	reassign the current row indices (with modifications) as specified by map_to_old More...

int	add_delete_blocks (const CH_Matrix_Classes::Indexmatrix &del_ind, CH_Matrix_Classes::Indexmatrix &map_to_old)
	delete the rows indexed by the vector del_ind and return the index changes of the others in a vector map_to_old More...

int	add_reset_generating_primal (PSCPrimal *new_generating_primal)
	replace the current generating primal by new_generating_primal (on the heap, will be deleted here). It may be NULL to switch of generating primals. More...

int	set_skip_extension (bool skip)
	if this time no extension is possible for newly added variables with the availabel generating primal, set this to true;

Routines for applying the collected modifications
int	apply_to_PSCAffine (SparseCoeffmatMatrix offset, SparseCoeffmatMatrix matrix) const
	carry out the collected modifications on the data describing the PSCAffineFunction More...

Routines for querying properties of the collected modifications
bool	no_modification () const
	returns true if no modifications need to be executed

int	set_append_to_old (bool append_only)
	if set to true, no deletions/reassignments may be present or specified in the future, only appensions are allowed

bool	append_to_old () const
	returns true if this only contains appending operations and incorporating this is done with respect to the old dimension

bool	deleted_variables_are_zero (const CH_Matrix_Classes::Matrix &oldpoint, const SparseCoeffmatMatrix &oldmat) const
	returns true if all entries deleted in oldpoint (must be a vector of length old_vardim()) or the corresponding entries in the old matrix are 0 and false otherwise

bool	new_variables_are_zero (const CH_Matrix_Classes::Matrix &newpoint, const SparseCoeffmatMatrix &newmat) const
	returns true if for all indices of new variables the entries in newpoint (must be a vector of length new_vardim()) or the matrices in newmat are 0 and false otherwise

bool	mapped_variables_are_equal (const CH_Matrix_Classes::Matrix &newpoint, const CH_Matrix_Classes::Matrix &oldpoint) const
	returns true if the values in newpoint (must be a vector of length new_vardim()) that correspond to old variables match the old values stored in oldpoint (must be a vector of length old_vardim()) and false otherwise

bool	variable_modifications () const
	returns true if some modifications are performed on the block structure

bool	block_modifications () const
	returns true if some modifications are performed on the block structure

Routines for retrieving the detailed collected modifications
CH_Matrix_Classes::Integer	old_vardim () const
	returns the number of variables before modification (given on initialization)

CH_Matrix_Classes::Integer	new_vardim () const
	returns the number of variables once all stored modifications have been performed

CH_Matrix_Classes::Integer	appended_vardim () const
	returns the number of variables that are appended (due to later reassignmentds they may no longer be located at the end)

const CH_Matrix_Classes::Indexmatrix &	old_blockdim () const
	returns the number of rows before modification (given on initialization)

const CH_Matrix_Classes::Indexmatrix &	new_blockdim () const
	returns the number of rows once all stored modifications have been performed

const CH_Matrix_Classes::Indexmatrix &	appended_blockdim () const
	returns the number of rows that are appended (due to later reassignments they may no longer be located at the end)

const CH_Matrix_Classes::Indexmatrix *	map_to_old_variables () const
	returns null if there are no index changes, otherwise the Indexmatrix pointed to is a vector whose i-th entry holds the old index of the new i-th variable (injective!), index values exceeding old_vardim() refer to newly appended variables

const CH_Matrix_Classes::Indexmatrix *	deleted_var_indices () const
	returns null if there were no deletions, otherwise the Indexmatrix pointed to is a vector holding the deleted old variable indices in increasing order

const CH_Matrix_Classes::Indexmatrix *	new_var_indices () const
	returns null if no variables were added, otherwise the Indexmatrix pointed to is a vector holding the new indices of the new variables in increasing order

const CH_Matrix_Classes::Indexmatrix *	map_to_old_blocks () const
	returns null if there are index changes, otherwise the Indexmatrix pointed to is a vector whose i-th entry holds the old index of the new i-th row (injective!), index values exceeding old_rowdim() refer to newly appended rows

const CH_Matrix_Classes::Indexmatrix *	deleted_block_indices () const
	returns null if there were no deletions, otherwise the Indexmatrix pointed to is a vector holding the deleted old row indices in increasing order

const CH_Matrix_Classes::Indexmatrix *	new_block_indices () const
	returns null if no rows were added, otherwise the Indexmatrix pointed ato is a vector holding the new indices of the new rows in increasing order

const SparseCoeffmatMatrix &	get_var_append () const
	returns null if nothing or default values have to be appended, otherwise it points to a sparse matrix whose columns need to be appended to the matrix

const SparseCoeffmatMatrix &	get_block_append () const
	returns null if nothing or default values have to be appended, otherwise it points to a sparse matrix whose rows need to be appended to the matrix

const SparseCoeffmatMatrix &	get_offset_append () const
	returns null if nothing or default values have to be appended, otherwise it points to a matrix whose entries need to be appended to the right hand side lower bounds vector

bool	get_reset_primal () const
	returns true if the generating primal is to be replaced by the one stored here

const PSCPrimal *	get_generating_primal () const
	returns the generating primal pointer stored here (may be NULL); if get_reset_primal() is true, the PSCAffineFunction should either delete its generating primal (NULL) or replace its generating primal by a clone of this one

bool	get_skip_extension () const
	returns true if the generating primal is to be replaced by the one stored here

Routines implementing the abstract OracleModifcation messages
int	get_old_vardim () const
	returns the number of variables before modification

int	get_new_vardim () const
	returns the number of variables once all stored modifications have been performed

int	get_appended_vardim () const
	returns the number of variables that are appended (due to later reassignmentds they may no longer be located at the end)

const int *	get_map_to_old_variables () const
	returns null if there are no index changes, otherwise the Indexmatrix pointed to is a vector whose i-th entry holds the old index of the new i-th variable (injective!), index values exceeding old_vardim() refer to newly appended variables

int	incorporate (const OracleModification &m)
	add the modification specified in m on top of the modifications collected so far More...

OracleModification *	new_initial_oraclemodification (int old_var_dim) const
	returns a new object on the heap, that allows to incorporate this but starts off from a function whose input argument dimension is old_var_dim

int	add_append_variables (int append_dim)
	append append_dim further variables at the end of the argument vector (without specifying their effect, they may e.g. be ignored by the function)

virtual int	add_reassign_variables (int new_dim, const int *map_to_old_indices)
	reorder and resize the variables as given by the first new_dim entries of map_to_old_indices; each former index may appear at most once in this list, so new_dim < get_new_vardim()

Output settings
void	set_cbout (const CBout *out, int incr=-1)
	see CBout::set_cbout

void	set_out (std::ostream *out=0, int print_level=1)
	see CBout::set_out

Public Member Functions inherited from ConicBundle::ModificationBase
virtual	~ModificationBase ()

	ModificationBase (const CBout *cbout=0, int incr=0)

Public Member Functions inherited from ConicBundle::CBout
void	clear_cbout ()
	reset to default settings (out=0,print_level=1)

	CBout (const CBout *cb=0, int incr=-1)
	calls set_cbout

	CBout (std::ostream *outp, int pl=1)
	initialize correspondingly

	CBout (const CBout &cb, int incr=0)
	copy constructor

virtual bool	cb_out (int pl=-1) const
	Returns true if out!=0 and (pl<print_level), pl<0 should be used for WARNINGS and ERRORS only, pl==0 for usual output.

std::ostream &	get_out () const
	If cb_out() returned true, this returns the output stream, but it will abort if called with out==0.

std::ostream *	get_out_ptr () const
	returns the pointer to the output stream

int	get_print_level () const
	returns the print_level

virtual int	mfile_data (std::ostream &out) const
	writes problem data to the given outstream

Private Attributes
bool	append_only
	if true, only appending operations are allowed and incorporating this has a different effect

Modification information for variables/columns
CH_Matrix_Classes::Integer	var_olddim
	initial number (or dimension) of variables

CH_Matrix_Classes::Integer	var_newdim
	number (or dimension) of variables after all listed modifications have been applied

CH_Matrix_Classes::Integer	var_append_dim
	number of variables appended

SparseCoeffmatMatrix	var_append
	columns to be appended for these new variables

CH_Matrix_Classes::Indexmatrix *	var_del_ind
	indices of variables that will be deleted by the reassignment of indices by map_to_old after all additions have been carried out

CH_Matrix_Classes::Indexmatrix *	var_map_to_old
	the variables are rearranged so that the new index i had previously (after additions and before deletion) the index map_to_old(i)

CH_Matrix_Classes::Indexmatrix *	var_new_ind
	in the end the appended new variables have these positions

Modification information for blocks (rows)
CH_Matrix_Classes::Indexmatrix	block_olddim
	initial number of blocks and their dimension

CH_Matrix_Classes::Indexmatrix	block_newdim
	number of blocks and their dimension after all listed modifications have been applied

CH_Matrix_Classes::Indexmatrix	block_append_dim
	number of blocks appended with their dimension

SparseCoeffmatMatrix	offset_append
	offset blocks to be appended;

SparseCoeffmatMatrix	block_append
	rows to be appended;

CH_Matrix_Classes::Indexmatrix *	block_del_ind
	indices of rows that will be deleted by the reassignment of indices by map_to_old after all additions have been carried out

CH_Matrix_Classes::Indexmatrix *	block_map_to_old
	the rows are rearranged so that the new index i had previously (after additions and before deletions) the index map_to_old(i)

CH_Matrix_Classes::Indexmatrix *	block_new_ind
	in the end the appended new rows have these positions

Modification information for primal aggregation
bool	reset_primal

PSCPrimal *	generating_primal
	primal to reset to

bool	skip_extension
	if set to true, no extension is performed on newly added variables

Additional Inherited Members
Protected Member Functions inherited from ConicBundle::ModificationBase
int	adapt_map_to_old (CH_Matrix_Classes::Indexmatrix &adapt_this_map, CH_Matrix_Classes::Indexmatrix &del_ind, CH_Matrix_Classes::Indexmatrix *&new_ind, CH_Matrix_Classes::Indexmatrix &append_del_ind, const CH_Matrix_Classes::Indexmatrix &input_map, CH_Matrix_Classes::Integer &append_dim, CH_Matrix_Classes::Integer olddim, CH_Matrix_Classes::Integer newdim) const
	internal routine for changing the maps in either of add_reassign_vars and add_reassign_rows More...

int	form_map_to_old (CH_Matrix_Classes::Indexmatrix &map_to_old, const CH_Matrix_Classes::Indexmatrix &del_ind, CH_Matrix_Classes::Integer dim) const
	internal routine that converts in either of add_delete_vars and add_delete_rows the list of indices to be deleted into a map_to_old that may the be treated in add_reassign_vars or add_reassign_rows respectively. Returns the number of errors detected in the input map. In case of errors, the returned map will not be valid.

Detailed Description

class for collecting and organizing a sequence of changes to block diagonal symmetric affine matrix functions so that it can be carried out in one step later on;

The general setting assumed here is to support changes for a function of the form

$\left[\begin{array}{ccc}C_1& & 0\\&\ddots&\\0& &C_k\end{array}\right]+\sum_{j=1}^m y_j\left[\begin{array}{ccc}A_{1,j}& & 0\\&\ddots&\\0& &A_{k,j}\end{array}\right]$

The data is thought as given by a (column) vector of pointers to matrices C_i and a k times m matrix calA where row i holds the pointers to matrices A_{i,j} for variable y_j, j=1,...,m. Note, because matrices are considered potentially hug objects this class never copies or deletes any matrices but only deals with the pointers to the matrices!

Supported are an arbitrary sequence of

appending variables (add_append_vars()), i.e. appending further "columns" of blockdiagonal matrices to .
reassigning the variables (add_reassign_vars()) via an index vector whose entries specify which variable will be moved to this position. Each existing variable index may appear at most once in this index vector, but not all indices need to appear. If they do not appear they will be deleted.
deleting variables (add_delete_vars()); the indices to be deleted are specfied by an index vector, which is then used to generate an index vector as a map to the old indices and then uses this with the previous reassign variables.
appending diagonal blocks (add_append_blocks()), i.e. appending further rows to A and further elements to C.
reassigning the blocks (add_reassign_blocks()) in the same style as reassigning variables
deleting diagonal blocks (add_delete_blocks()) in the same style as deleting variables

Each next modification has to be given/added with respect to the current virtual number of variables and blocks as if the compiled modifications had been carried out already. If certain elements are not specified, they are assumed to be zero

The modifications are compiled within this class (and not yet executed) to one bulk of data of appending information for variables and blocks and reassignment information, so that the entire sequence of transformations is then achieved in the following sequence of four steps (the sequence is important here!)

appending the compiled variable (and column) data
reassigning the variables (and columns) by the compiled variable reassignment map
appending the compiled block (row) data
reassigning the blocks (rows) by the compiled block reassignment map

Further modifications can be incorporated into this one if the dimensions match the current values.

In the end the routines apply_to_vars() and apply_to_blocks() can be used to carry out the modifications on a SparseCoeffmatMatrix.

Member Function Documentation

◆ add_append_blocks()

int ConicBundle::PSCAffineModification::add_append_blocks	(	const CH_Matrix_Classes::Indexmatrix &	append_dim,
		const SparseCoeffmatMatrix *	append_offsets,
		const SparseCoeffmatMatrix *	append_blocks
	)

append information on new rows at the respective ends

Parameters

append_dim	the dimension gives the number of (diagonal) blocks and each entry the order of the block to be appended
append_blocks	if NULL, append zero matrics, otherwise it must point to a sparse matrix of size append_dim times new_vardim() that is to be appended to the constraint matrix below.
append_offsets	if NULL, append zero matrices, otherwise it must point to a column vector of size append_dim that is to be appended to the vector of offsets

Returns: number of errors; if errors occured, none of the new changes are performed

◆ add_append_vars()

int ConicBundle::PSCAffineModification::add_append_vars	(	CH_Matrix_Classes::Integer	append_dim,
		const SparseCoeffmatMatrix *	append_cols
	)

append information on new variables at the respective ends

Parameters

append_dim	number of variables (or columns ) to be appended
append_cols	if NULL, append zero matrices, otherwise it must point to a sparse matrix of size new_rowdim() times append_dim that is to be appended to the constraint matrix on the right

Returns: number of errors; if errors occured, none of the new changes are performed

Referenced by add_append_variables().

◆ add_delete_blocks()

int ConicBundle::PSCAffineModification::add_delete_blocks	(	const CH_Matrix_Classes::Indexmatrix &	del_ind,
		CH_Matrix_Classes::Indexmatrix &	map_to_old
	)

delete the rows indexed by the vector del_ind and return the index changes of the others in a vector map_to_old

del_ind need not be ordered in any way, but any index in 0 to new_rowdim()-1 may appear at most once. On output the dimension of the column vector map_to_old gives the number of remaining rows and its entry i holds the index the row with new index i had before the deletion. The return value is the number of errors in del_ind. If such occured, this deletion is not performed and map_to_old may contain garbage.

◆ add_delete_vars()

int ConicBundle::PSCAffineModification::add_delete_vars	(	const CH_Matrix_Classes::Indexmatrix &	del_ind,
		CH_Matrix_Classes::Indexmatrix &	map_to_old
	)

delete the variables indexed by the vector del_ind and return the index changes of the others in a vector map_to_old

del_ind need not be ordered in any way, but any index in 0 to new_vardim()-1 may appear at most once. On output the dimension of the column vector map_to_old gives the number of remaining variables and its entry i holds the index the variable with new index i had before the deletion. The return value is the number of errors in del_ind. If such occured, this deletion is not performed and map_to_old may contain garbage.

◆ add_reassign_blocks()

int ConicBundle::PSCAffineModification::add_reassign_blocks ( const CH_Matrix_Classes::Indexmatrix & map_to_old )

reassign the current row indices (with modifications) as specified by map_to_old

map_to_old must specify an injective map (no two values match) into indices 0 up to new_rowdim()-1 (not all need to appear). The row getting index i (for i=0 to map_to_old.dim()-1) is the row with current index map_to_old(i) (current refers to considering all previous modifications as having been carried out already). The return value is the number of errors in map_to_old. If such occured, this reassign is not performed.

◆ add_reassign_vars()

int ConicBundle::PSCAffineModification::add_reassign_vars ( const CH_Matrix_Classes::Indexmatrix & map_to_old )

reassign the current variable indices (with modifications) as specified by map_to_old

map_to_old must specify an injective map (no two values match) into indices 0 up to new_vardim()-1 (not all need to appear). The variable getting index i (for i=0 to map_to_old.dim()-1) is the variable with current index map_to_old(i) (current refers to considering all previous modifications as having been carried out already). The return value is the number of errors in map_to_old. If such occured, this reassign is not performed.

Referenced by add_reassign_variables().

◆ add_reset_generating_primal()

int ConicBundle::PSCAffineModification::add_reset_generating_primal ( PSCPrimal * new_generating_primal )

replace the current generating primal by new_generating_primal (on the heap, will be deleted here). It may be NULL to switch of generating primals.

Any changes here cause the deletion of all current aggregate minorants. If not NULL, the object pointed to is on the heap and control over it is passed over to *this, so *this will make sure it is deleted at due time.

PSCPrimal gives no information on the order of the matrices involved, so no consistency checks are done here.

◆ apply_to_PSCAffine()

int ConicBundle::PSCAffineModification::apply_to_PSCAffine	(	SparseCoeffmatMatrix *	offset,
		SparseCoeffmatMatrix *	matrix
	)		const

carry out the collected modifications on the data describing the PSCAffineFunction

If a specific parameter is NULL, no changes are performed on it, if it is not null, it must point to a SparseCoeffmatMatrix whose sizes correspond to the "old" data. Then the following operations will be performed on it in this sequence:

new variables (columns) are appended to the matrix
if reassignment information is given, the columns are mapped/reorderd as given by *map_to_old_variables()
new blocks (rows) are appended to the offset and the matrix
if reassignment information is given, the rows are mappen/reorderd as given by *map_to_old_blocks()

Parameters

[in,out]	offset	if not NULL, this points to the offset vector.
[in,out]	matrix	if not NULL, this points to the old matrix.

Returns: the number of dimension errors of non NULL inputs, if any, no modifications are made to any inputs.

◆ clear()

int ConicBundle::PSCAffineModification::clear	(	CH_Matrix_Classes::Integer	var_olddim,
		const CH_Matrix_Classes::Indexmatrix &	block_olddim
	)

resets all variables so that the object to be modified has starting size var_olddim (number of variables) and block_olddim (number of rows) and no modifications

The actual old data is not needed at this point, the changes on it will be collected and excuted in the routines apply_to_vars and apply_to_blocks

Setting the parameter ensure_start_val_box_feasibility to true will cause the algorithm to check in add_append_vars() whether the input values are within the given bounds and in apply_to_vars() it will project all start_values onto the bounds for all, old and new, indices (which might have been changed by then). If it is false (default), all values will be accepted as given.

Setting the parameter ensure_bounds_consistency to true (default) will raise errors in add_append_vars() and in apply_to_vars() whenever there are lower bounds greater than the respective upper bounds so as to avoid trivial infeasibilities. This check is omitted if set to false.

The remaining values give the values of plus and minus infinity the no bounds should exceed. These are the default values at the same time (maybe it might be good to have a separate default value, but this is not implemented here).

◆ incorporate()

int ConicBundle::PSCAffineModification::incorporate ( const OracleModification & m )

virtual

add the modification specified in m on top of the modifications collected so far

If m is in fact an PSCAffineModification, the old_vardim() of modification m must be identical to new_vardim() of this and old_rowdim() of modification m must be identical to new_rodim() of this. The return value is the number of errors in this respect. If such occured, this incorporation is not performed.

A general OracleModification m should only contain variable changes (this is not checked) and appending variables appends zero blocks.

Implements ConicBundle::OracleModification.

Referenced by get_map_to_old_variables().

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