function helpDec
% This is a documentation m-file for the decomposition structure
%
% Content:
%   <a href="matlab: help obtainDec">Generating function</a>
%   <a href="matlab: help helpDec>decDetail">Details on entities</a>
%   <a href="matlab: help helpDec>decOutput">Field structure for dec</a>
%     > <a href="matlab:help helpDec>decConeField">Subfields for cones</a>
clc
help helpDec
disp('')
disp('  ---------------------------')
end

function decDetail
% The validity cone defines constrained h-vectors (hC-vectors) for which all
%   facets, defined by the facet normals in A, are supporting hyperplanes 
%   that touch the polytope. For all limiting cases, that are:
%     dec.validityCone.A * hC = 0
%   one or more facets are not present. Extended information that includes
%   the set of facet that are acutally vanished can be obtained by
%   dec.boundaryData for which redundant rows of A are stored.
%
% The unified partitions define the regions in hC-space for which the
%   polytopes have the same a-type (in 3D: the same set of faces, edges and
%   vertices). These partitions also contain the limiting cases, where
%   edges are reduced to vertices. They are defined, by:
%     dec.unifiedPartition{iPart}.A * hC <= 0
%
% The simplex partitions are the triangulation of the unified partition and
%   are required interenally only.
%
% The structuring elements (dec.se) are those indecomposable polytopes 
%   that are used to represent a polytope from H-representation in 
%   S-representation:
%     P(hC) = [Minkowski sums over i:] lam(i) * P(dec.se(i, :)').
%   The structuring elements are given as hC-vectors in each line of dec.se
%   and they are normalized to the mean width of 1.
%
% The center ray (dec.centerRay) is computed by the mean of the extreme
%   rays of the validity cone. It is used to scale the structuring elements in
%   hC-space to reside on the hyperplane, defined by:
%     dec.centerRay * hC = 1,
%   which touches the unit ball in hC-space. It is also used to close the
%   cones of the validity cone and partitions.
%
% Back to <a href="matlab: helpDec">Content</a>
% ---------------------------
end

function decOutput
% Fields of a decomposition structure:
%   .A - the facet normals of the polytope (nH x nDim matrix)
%   .mappingReducedToFull - mapping matrix h = M*hC (nH x nC matrix)
%   .mappingFullToReduced - mapping matrix hC = M*h (nC x nH matrix)
%   .constraintMatrix - constraints that h fulfills: C*h = 0 
%          (nH x nH matrix)
%
%   .nDim - dimensionality of the polytopes defined by A
%   .nH   - total number of facets defined by A
%   .nC   - dimension of the constrained h-vectors (hC-vectors)
%   .properData - (optional for improper representations) the decomposition
%          structure; it has some additional fields to map proper and 
%          improper (new) representaiton: .mappingNewToProper, 
%          .mappingProperToNew
%
%   .isProper   - 1 if representation is proper (validity=confinement)
%   .isOrdinary - 0 if representation is singular (no confinement mapping;
%          confinement cone is not convex)
%   .isComplete - 1 if representation is complete (validity cone is known)
%
%   .confinementCone - the cone of confined hC-vectors (more <a href="matlab:help helpDec>decConeField">subfields</a>)
%   .confinementConeHull - substitutes confinementCone for singular
%          representations
%   .confinemendConePart - substitutes confinementCone for incomplete
%          representations
%   .validityCone - the cone of valid hC-vectors (more <a href="matlab:help helpDec>decConeField">subfields</a>)
%   .validityConePart - substitutes validityCone for incomplete
%          representations
%   .confinementMappingData - data required for mapping unconfinement 
%          vectors to the confinement cone (see <a href="matlab:help mapToValidityCone">mapToValidityCone</a>; more
%          <a href="matlab:help helpDec>decConfinementMappingField">subfields</a>)
%   .validityMappingData - data required for mapping invalid (but usually 
%          confined) vectors to the validity cone (see <a href="matlab:help mapToValidityCone">mapToValidityCone</a>; more
%          <a href="matlab:help helpDec>decValidityMappingField">subfields</a>)
%   .facetValidityData - data used by <a href="matlab:help obtainFacetValidityCone">obtainFacetValidityCone</a> (more
%          <a href="matlab:help helpDec>decFacetValidityField">subfields</a>)
%   .centerRay - a normalized hC-vector that represents mean of the
%          structuring elements (this is an inner point for ordinary
%          representations)
%
%   .simplexPartition - cell array of simplex partitions (more <a href="matlab:help helpDec>decConfinementMappingField">subfields</a>)
%   .simplexPartition - cell array of unified partitions (more <a href="matlab:help helpDec>decConfinementMappingField">subfields</a>)
%   .se - the nS structuring elements, scaled to mean width 
%          of one (nS x nC matrix)
%   .seScaledToClose  - the nS structuring elements, scaled the closure 
%          constructed by the .centerRay (nS x nC matrix)
%   .seIncidenceMatrix - structuring elements that can be Minkowski added
%          pairwise so that no additional facets are created. (0 not 
%          possible, 1 possible; nS x nS matrix)
%   .simplexToUnifiedVector - a vector of length nPS that contains the 
%          index to the unified partition from which each simplex partition
%          was generated from.
%   .nS  - total number of structuring elements
%   .nPU - total number of unified partitions
%   .nPS - total number of simplex partitions
%
%   .measureData - data generated by <a href="matlab:help addMeasureDataDec">addMeasureDataDec</a> and used by
%          <a href="matlab:help computeMeasureDec">computeMeasureDec</a>
%   .inputData - (internal use, only)
%   .cdef - optionally added, when created by obtainCrystalDec
%   .timingData - storage of cumputational times (internal use, only)
%
% Back to <a href="matlab: helpDec">Content</a>
% ---------------------------
end

function decConeField
% The fields of cones for a decomposition have the following fields:
%     .A       - facet normals of the cone in nC-dimensional space
%     .h       - facet distances of the cone (they are always zero; in this
%                way the cone can be used directly as hrep)
%     .volume  - the volume of the closed cone in hC-space
%                (.confinementCone and .validityCone, only)
%     .volumeScaled - the volume of the closed cone divided by the
%                confinement cone volume (.simplexPartition and
%                .unifiedPartition, only)
%     .seIndexVector - indices to dec.se that are the generating rays of
%                this cone
%     .mappingHcToLam - a mapping matrix to convert a hC vector to the
%        scalar coefficients of the Minkowski decomposition with the
%        structuring elments in seIndexVector
%
% Back to <a href="matlab: helpDec">Content</a>
% Back to <a href="matlab:help helpDec>decOutput">decomposition structure</a>
% ---------------------------
end

function decConfinementMappingField
% The fields dec.confinementMappingData are:
%   .A - matrix of normals for linear inequality constraints
%   .responsibleVector - each inequality (columns) is assigned to a set
%      of projections in .projectionData; for proper representations the
%      value indicates a group of facets that disappeared
%   .projectionData - structure array with subfields:
%      .A - matrix of normals for linear inequality constraints
%      .responsibleMatrix - indicates which equations (first column) must
%         be fulfilled as <= or >= (third column) so that the projection
%         in projectionList with index in the first column can be applied
%      .projectionList - a cell array of projection matrices
%   .ignoreFadeOut - this field only applies for the proper embedding of
%      improper representations and indicates indices to constraints for
%      which a growth vector shall not be slowed down when approaching this
%      boundary (see also pbeSolver).
%
% Back to <a href="matlab: helpDec">Content</a>
% Back to <a href="matlab:help helpDec>decOutput">decomposition structure</a>
% ---------------------------
end

function decValidityMappingField
% The fields dec.validityMappingData are:
%   .A - matrix of normals for linear inequality constraints
%   .responsibleMatrix - indicates which equations (first column) must
%        be fulfilled as <= or >= (third column) so that the projection
%        in projectionList with index in the first column can be applied
%   .projectionList - a cell array of projection matrices
%   .targetDimension - corresonding to the projection matrix in
%        .projectionList, it indicates the rank of the projection matrix
%
% Back to <a href="matlab: helpDec">Content</a>
% Back to <a href="matlab:help helpDec>decOutput">decomposition structure</a>
% ---------------------------
end

function decFacetValidityField
% The fields dec.facetValidityData are:
%   .A - matrix of all facet normals used for facet validity cones
%   .responsibleMatrix - indicates which facet normals (first column) are
%        used for the facet validity cone of the index in the second
%        column (index (.nH+1) represents the empty polytope cone)
%
% Back to <a href="matlab: helpDec">Content</a>
% Back to <a href="matlab:help helpDec>decOutput">decomposition structure</a>
% ---------------------------
end