function helpPbeSolver
% This is a documentation m-file for the PBE solver
%
% Content:
%   <a href="matlab: help solvePbe">Calling the PBE solver</a>
%     > <a href="matlab: help helpPbeSolver>optionValuePairs">List of option/value pairs</a>
%   <a href="matlab: help helpPbeSolver>variables">Nomenclature  for input/output structures</a>
%   <a href="matlab: help helpPbeSolver>inputStruct">Input structure: pbeDefinition</a>
%     > <a href="matlab: help helpPbeSolver>seedingStruct">Structure for a seeding event.</a>
%   <a href="matlab: help helpPbeSolver>outputStruct">Output structure array: result</a>
clc
help helpPbeSolver
disp('')
disp('  ---------------------------')
end

function variables
% The description of the input and output structures use the following 
%   nomenclature:
%     H - matrix with facet distances (column=crystal, row=dimension)
%       h - single column of H
%     P - matrix of (user) crystal properties (column=crystal, row=property)
%       p - single row of P
%     N - vector of particle number assigned to pivot
%     x - vector of bulk states
%     y - vector of bulk properties
%     up - the vector of the unified partition for each pivot
%
% Back to <a href="matlab: helpPbeSolver">Content</a>
% ---------------------------
end


function inputStruct
% The input structure pbeDefinition consists of the fields:
%   .timeSpan - time interval for simulation
%   .dec      - decomposition data including relevant measure information
%
%   .seeding - a structure array that is also used for the initial
%       condition (support for multiple seeding is currently cancelled). 
%       The fields are documented <a href="matlab: help helpPbeSolver>seedingStruct">here</a>.
%   .growthRate - handle @(H, P, y, t) that is the time derivative of the
%       facet distances h. Disappearing facets (the validity of h) are 
%       treated internally.
%   .pivotProperty - handle @(H, up) that is a (geometric) property of 
%       the crystal represented by h (e.g. volume, surface area).
%       Alternatively, this is a list (cell array {}) of measure 
%       definitions used as input to computeMeasureDec.
%
%   .bulkInitial - state vector with the initial condition
%   .bulkRate - handle @(y, t) that is the time derivative of the bulk 
%       state vector x
%   .bulkProperty - handle @(P, N, x, t) that is the vector of bulk properties
%       (e.g. total particle volume, supersaturation)
%
%   .nucleationSize - vector of facet distances of the nuclei
%   .nucleationRate - handle @(y, t) that gives the nucleation rate
%
%   .option - a structure with additional solver parameters. The fieldnames
%       are the option names used in <a href="matlab: help solvePbe">solvePbe</a>. The options in this 
%       structure are overwritten when the same options are provided during
%       a call of solvePbe.
%
%   .nDecCoordinates - the number of coordinates in the positionMatrix that
%       must match .dec.nC; default value dec.nC
%   .nExtraCoordinates - shape coordinates that are contained in the last n
%       rows of H; default value 0
%
% Back to <a href="matlab: helpPbeSolver">Content</a>
% ---------------------------
end

function seedingStruct
% The fields for the definition of a seeding event are:
%   .time - time of seed injection (discrete time event).
%   .positionMatrix - discrete particle population
%   .numberVector - contains the number of particles that are represented 
%       by the corresponding position. If the distribution is generated by
%       distribution densities, the particle number equals the density 
%       value divided by the probability value.
%   .probabilityVector - the probability density value for choosing the
%       corresponding position.
%
% Back to <a href="matlab: helpPbeSolver">Content</a>
% Back to <a href="matlab: help helpPbeSolver>inputStruct">input structure: pbeDefinition</a>
% ---------------------------
end

function outputStruct
% The output structure array result(:) consists of the fields:
%   .time           - timestamp
%   .evaltime       - seconds passed until a result step is entered
%   .flagDensity    - is 1, if distribution densities are used and 0 
%                     otherwise
%   .flagNucleation - is 1, if the first element(s) of hCmatrix represent 
%                     the nucleation bin.
%
%   .bulkStateVector - vector of bulk states
%   .hcMatrixDynamic - matrix of pivots that represent the population
%     (unaltered state variables)
%   .hcMatrix - matrix of pivots that represent the population (these are
%     valid and might be formulated in the proper emebedding, dependend on
%     the useEmbeddingPartitions option)
%   .numberVector - vector with the particle numbers assigned to the pivots
%   .upVector - vector of unified partitions for hC-vectors, they are
%       generated as intitial guess and might be wrong.
%   .probabilityVector - the probability density of the pivot point (only
%       available if calculated with densities)
%   .indexVector - contains integer values for the origin of the hC-vector
%       (positive integers as index to a seeding population; -1 for pivots
%       of the nucleation process; -2 for the active nucleation pivot)
%   .dissolvedPivotVector - a vector that contains the total number of 
%       removed pivots for each seeding population.
%
%   .pivotPropertyMatrix - pivot properties re-calculated for each timestep
%   .bulkPropertyVector  - bulk properties re-cacluated for each timestep
%
% Back to <a href="matlab: helpPbeSolver">Content</a>
% ---------------------------
end

function optionValuePairs
% The call solvePbe(.., 'option', value) supports a list of option/value
%   pairs that are described in the following including their standard
%   values. The standard values can be overwritten by the fields of
%   pbeDefinition.option. But the settings from pbeDefinition.option are
%   overwritten by the options given by a function call. The option/value
%   pairs are:
%     verbose - verbosity level {2}
%
%     odeSolver: a function handle for the ode solver that shall be applied
%         {@ode45}
%     initialTimeStep: the size of the initial time step to be used by the 
%         ode solver {1}
%     distanceLimit: growth rates are continuously adopted to the limited
%         growth rate as soon as they have a distance of this value from
%         the validity/confinement cone; particles are also considered
%         dissolved when they have a distance of that value from the
%         empty-polytope cone {1e-8}
%     updateUnifiedLimit: the algorithm stores the unified partition index
%         for each hC-vecor and searches for the correct unified parition
%         only if the hC-vector has left the stored unified partition. This
%         option gives the percentage of hC-vectors that have left the
%         unified partition and at which point in time the unified 
%         partition index is updated for all hC-vectors before time 
%         integration continues (time discrete event) {0.3}
%     useEmbeddingPartitions: if improper representations are used, (1)
%         uses the embedding proper representation for the stored hcMatrix
%         and the computed unified partitions. For (0), the improper values
%         are used. {1}
%
%     relTol:         relative tolerance for all state variables {1e-5}
%     absTolPosition: absolute tolerance for hC-vectors {1e-12}
%     absTolBulk:     absolute tolerance for the bulk properties {1e-12}
%     absTolDensity:  absolute tolerance for the distribution density (if 
%         applied) {1e8}
%     absTolNumber:   absolute tolerance for the particle number (applies
%         for nucleation only since the particle number for seeding 
%         populations is constant) {1e10}
%     binLoad: absolute maximum value for a nucleation bin even though 
%         nucleation is not yet supported {1e17}
%
%     density: flag to consider the dynamical evolution of the probability
%         distribution (1) or not (0) {0}
%     gradientRelativeDelta: relative delta to be used for hC-vectors to 
%         estimate the gradient of the growth rate (applies only for 
%         density=1) {1e-3}
%     gradientAbsoluteDelta: absolute delta to be used for hC-vectors to 
%         estimate the gradient of the growth rate (applies only for 
%         density=1) {1e-10}
%
% Back to <a href="matlab: helpPbeSolver">Content</a>
% ---------------------------
end