From 13d3f48c0cc55b90dbcd6b860f14a7ee51a485d9 Mon Sep 17 00:00:00 2001 From: leburgel Date: Wed, 7 Feb 2024 20:30:20 +0100 Subject: [PATCH] Update tensor docs, set up doc stubs for other modules. --- docs/src/lib/algorithms.rst | 32 ++- docs/src/lib/caches.rst | 2 +- docs/src/lib/environments.rst | 2 +- docs/src/lib/models.rst | 29 ++- docs/src/lib/mps.rst | 20 +- docs/src/lib/sparse.rst | 3 +- docs/src/lib/utility.rst | 39 +++- src/algorithms/Dmrg.m | 81 +++++++- src/algorithms/Expand.m | 90 +++++++- src/algorithms/IDmrg.m | 70 ++++++- src/algorithms/IDmrg2.m | 77 ++++++- src/algorithms/QPAnsatz.m | 44 +++- src/algorithms/Vomps.m | 94 ++++++++- src/algorithms/Vumps.m | 102 ++++++++- src/algorithms/eigsolvers/Arnoldi.m | 61 ++++-- src/algorithms/eigsolvers/KrylovSchur.m | 51 +++-- src/caches/DLL.m | 31 +-- src/caches/GetMD5/GetMD5.m | 4 +- src/caches/GetMD5/GetMD5_helper.m | 2 +- src/caches/GetMD5/InstallMex.m | 10 +- src/caches/GetMD5/uTest_GetMD5.m | 4 +- src/caches/LRU.m | 47 +++-- src/environments/FiniteEnvironment.m | 17 +- src/models/fermionoperators/c_min.m | 11 + src/models/fermionoperators/c_number.m | 6 + src/models/fermionoperators/c_plus.m | 11 + src/models/quantum1dHeisenberg.m | 29 ++- src/models/quantum1dHubbard.m | 21 +- src/models/quantum1dIsing.m | 24 +++ src/models/spinoperators/sigma_exchange.m | 14 ++ src/models/spinoperators/sigma_min.m | 14 ++ src/models/spinoperators/sigma_plus.m | 14 ++ src/models/statmech2dIsing.m | 20 ++ src/mps/FiniteMpo.m | 21 +- src/mps/FiniteMps.m | 15 +- src/mps/InfJMpo.m | 6 +- src/mps/InfMpo.m | 9 + src/mps/InfQP.m | 30 +-- src/mps/MpoTensor.m | 18 +- src/mps/MpsTensor.m | 56 +++-- src/mps/PepsSandwich.m | 12 ++ src/mps/PepsTensor.m | 20 +- src/mps/UniformMps.m | 219 ++++++++++++-------- src/sparse/SparseTensor.m | 4 + src/tensors/Tensor.m | 16 +- src/utility/Options.m | 15 +- src/utility/Verbosity.m | 9 + src/utility/between.m | 1 + src/utility/colors.m | 1 + src/utility/dim2str.m | 1 + src/utility/diracdelta.m | 1 + src/utility/indices/contractinds.m | 2 +- src/utility/indices/mod1.m | 8 +- src/utility/indices/next.m | 4 +- src/utility/indices/prev.m | 4 +- src/utility/indices/rankrange.m | 3 +- src/utility/indices/traceinds.m | 4 + src/utility/indices/treeindsequence.m | 4 +- src/utility/indices/unique1.m | 2 +- src/utility/linalg/contract.m | 12 +- src/utility/linalg/eigsolve.m | 48 ++--- src/utility/linalg/isapprox.m | 19 ++ src/utility/linalg/isisometry.m | 14 +- src/utility/linalg/leftnull.m | 13 +- src/utility/linalg/leftorth.m | 32 ++- src/utility/linalg/rightnull.m | 16 +- src/utility/linalg/rightorth.m | 32 ++- src/utility/linalg/tensorprod.m | 20 +- src/utility/linalg/tensortrace.m | 10 +- src/utility/memsize.m | 5 + src/utility/mod1.m | 9 - src/utility/permutations/invperm.m | 6 +- src/utility/permutations/isperm.m | 7 +- src/utility/permutations/perm2swap.m | 8 +- src/utility/randc.m | 8 +- src/utility/randnc.m | 8 +- src/utility/simulsort.m | 6 +- src/utility/simulsortrows.m | 15 +- src/utility/simulunique.m | 2 +- src/utility/sparse/SparseArray.m | 152 ++++++++------ src/utility/swapvars.m | 2 +- src/utility/time2str.m | 6 +- src/utility/validations/mustBeEqualLength.m | 11 +- src/utility/validations/mustBeSorted.m | 11 +- src/utility/validations/mustBeUnique.m | 12 +- src/utility/wigner/Wigner3j.m | 13 +- src/utility/wigner/Wigner6j.m | 10 +- 87 files changed, 1616 insertions(+), 452 deletions(-) delete mode 100644 src/utility/mod1.m diff --git a/docs/src/lib/algorithms.rst b/docs/src/lib/algorithms.rst index 682363b..446c01d 100644 --- a/docs/src/lib/algorithms.rst +++ b/docs/src/lib/algorithms.rst @@ -8,13 +8,43 @@ Algorithms This section contains the API documentation for the :mod:`.algorithms` module. +Finite MPS algorithms +--------------------- + +.. autoclass:: src.algorithms.Dmrg + :no-members: + :members: fixedpoint + + Infinite MPS algorithms ----------------------- .. autoclass:: src.algorithms.Vumps + :no-members: + :members: fixedpoint + +.. autoclass:: src.algorithms.IDmrg + :no-members: + :members: fixedpoint + +.. autoclass:: src.algorithms.IDmrg2 + :no-members: + :members: fixedpoint + +.. autoclass:: src.algorithms.QPAnsatz + :no-members: + :members: excitations + +.. autoclass:: src.algorithms.Vomps + :no-members: + :members: approximate + +.. autoclass:: src.algorithms.Expand + :no-members: + :members: changebonds + Eigsolvers ---------- .. automodule:: src.algorithms.eigsolvers - diff --git a/docs/src/lib/caches.rst b/docs/src/lib/caches.rst index 323cbc7..23de751 100644 --- a/docs/src/lib/caches.rst +++ b/docs/src/lib/caches.rst @@ -10,8 +10,8 @@ This section contains the API documentation for the :mod:`.caches` module. .. automodule:: src.caches + GetMD5 ------ .. automodule:: src.caches.GetMD5 - diff --git a/docs/src/lib/environments.rst b/docs/src/lib/environments.rst index 1801d2f..cde31f8 100644 --- a/docs/src/lib/environments.rst +++ b/docs/src/lib/environments.rst @@ -8,5 +8,5 @@ Environments This section contains the API documentation for the :mod:`.environments` module. -.. automodule:: src.environments +.. autoclass:: src.environments.FiniteEnvironment diff --git a/docs/src/lib/models.rst b/docs/src/lib/models.rst index 9b62b20..6854de1 100644 --- a/docs/src/lib/models.rst +++ b/docs/src/lib/models.rst @@ -8,5 +8,32 @@ Models This section contains the API documentation for the :mod:`.models` module. -.. automodule:: src.models +.. Operators +.. --------- + +.. Spin operators +.. `````````````` + +.. .. autofunction:: src.models.spinoperators.sigma_min +.. .. autofunction:: src.models.spinoperators.sigma_plus +.. .. autofunction:: src.models.spinoperators.sigma_z +.. .. autofunction:: src.models.spinoperators.sigma_exhange + + +.. Fermion operators +.. ````````````````` + +.. .. autofunction:: src.models.fermionoperators.c_min +.. .. autofunction:: src.models.fermionoperators.c_plus +.. .. autofunction:: src.models.fermionoperators.c_number + + +.. Models +.. ------ + +.. autofunction:: src.models.quantum1dIsing +.. autofunction:: src.models.quantum1dHeisenberg +.. autofunction:: src.models.quantum1dHubbard + +.. autofunction:: src.models.statmech2dIsing diff --git a/docs/src/lib/mps.rst b/docs/src/lib/mps.rst index 6146b12..53e7d7e 100644 --- a/docs/src/lib/mps.rst +++ b/docs/src/lib/mps.rst @@ -8,5 +8,23 @@ MPS This section contains the API documentation for the :mod:`.mps` module. -.. automodule:: src.mps +States +------ +.. autoclass:: src.mps.MpsTensor +.. autoclass:: src.mps.FiniteMps + :no-members: +.. autoclass:: src.mps.UniformMps +.. autoclass:: src.mps.InfQP + + +Operators +--------- + +.. autoclass:: src.mps.MpoTensor +.. autoclass:: src.mps.FiniteMpo +.. autoclass:: src.mps.InfMpo +.. autoclass:: src.mps.InfJMpo +.. autoclass:: src.mps.PepsTensor +.. autoclass:: src.mps.PepsSandwich + :no-members: diff --git a/docs/src/lib/sparse.rst b/docs/src/lib/sparse.rst index 47e639f..7593aff 100644 --- a/docs/src/lib/sparse.rst +++ b/docs/src/lib/sparse.rst @@ -8,4 +8,5 @@ Sparse This section contains the API documentation for the :mod:`.sparse` module. -.. automodule:: src.sparse +.. autoclass:: src.sparse.SparseTensor + :no-members: diff --git a/docs/src/lib/utility.rst b/docs/src/lib/utility.rst index 6da2a9d..31eef3d 100644 --- a/docs/src/lib/utility.rst +++ b/docs/src/lib/utility.rst @@ -8,7 +8,38 @@ Utility This section contains the API documentation for the :mod:`.utility` module. -.. automodule:: src.utility +Options and verbosity +--------------------- + +.. autoclass:: src.utility.Options +.. autoclass:: src.utility.Verbosity + +.. IO and converters +----------------- + +.. .. autofunction:: src.utility.safesave +.. .. autofunction:: src.utility.clear_path +.. .. autofunction:: src.utility.mat2jl +.. .. autofunction:: src.utility.jl2mat + + +Toolbox +------- + +.. autofunction:: src.utility.between +.. autofunction:: src.utility.colors +.. autofunction:: src.utility.dim2str +.. autofunction:: src.utility.diracdelta +.. autofunction:: src.utility.memsize +.. .. autofunction:: src.utility.mod1 +.. .. autofunction:: src.utility.netcon +.. autofunction:: src.utility.randc +.. autofunction:: src.utility.randnc +.. autofunction:: src.utility.simulsort +.. autofunction:: src.utility.simulsortrows +.. autofunction:: src.utility.simulunique +.. autofunction:: src.utility.swapvars +.. autofunction:: src.utility.time2str Indices @@ -34,12 +65,6 @@ Sparse Arrays .. automodule:: src.utility.sparse -Uninit ------- - -.. automodule:: src.utility.uninit - - Validations ----------- diff --git a/src/algorithms/Dmrg.m b/src/algorithms/Dmrg.m index 6c6b107..0bf88b5 100644 --- a/src/algorithms/Dmrg.m +++ b/src/algorithms/Dmrg.m @@ -1,5 +1,51 @@ classdef Dmrg - % Density Matrix Renormalisation Group algorithm for marix product states. + % `Density Matrix Renormalisation Group algorithm `_ for marix product states. + % + % Properties + % ---------- + % tol : :class:`double` + % tolerance for convergence criterion, defaults to :code:`1e-10`. + % + % miniter : :class:`int` + % minimum number of iteration, defaults to 5. + % + % maxiter : :class:`int` + % maximum number of iteration, defaults to 100. + % + % verbosity : :class:`.Verbosity` + % verbosity level of the algorithm, defaults to :code:`Verbosity.iter`. + % + % doplot : :class:`logical` + % plot progress, defaults to :code:`false`. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. + % + % dynamical_tols : :class:`logical` + % indicate whether or not to use a dynamical tolerance scaling for the algorithm's + % subroutines based on the current error measure, defaults to :code:`false` + % + % tol_min : :class:`double` + % smallest allowed convergence tolerance for soubroutines, defaults to :code:`1e-12`. + % + % tol_max : :class:`double` + % highest allowed convergence tolerance for soubroutines, defaults to :code:`1e-10`. + % + % eigs_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the eigensolver + % subroutine based on the current error measure, defaults to :code:`1e-6` + % + % sweepstyle : :class:`char` + % sweep style indicating how to sweep through the MPS at each iteration, options are: + % + % - :code:`'f2f'`: (default) front-to-front, sweeping from site 1 to the end and back. + % - :code:`'b2b'`: back-to-back, sweeping from site N to the start and back. + % - :code:`'m2m'`: mid-to-mid, sweeping from the middle site to both ends and back. + % + % alg_eigs : :class:`.KrylovSchur` or :class:`.Arnoldi` + % algorithm used for the local eigsolver updates, defaults to + % :code:`KrylovSchur('MaxIter', 100, 'KrylovDim', 20)`. %% Options properties @@ -22,7 +68,7 @@ saveMethod = 'full' name = 'DMRG' - alg_eigs = KrylovSchur('MaxIter', 100, 'KrylovDim', 20) % TODO: Arnoldi has issues for DMRG specifically, need to figure out why + alg_eigs = KrylovSchur('MaxIter', 100, 'KrylovDim', 20) end properties (Access = private) @@ -49,6 +95,37 @@ end function [mps, envs, eta] = fixedpoint(alg, mpo, mps, envs) + % Find the fixed point MPS of a finite MPO, given an initial guess. + % + % Usage + % ----- + % :code:`[mps, envs, eta] = fixedpoint(alg, mpo, mps, envs)` + % + % Arguments + % --------- + % alg : :class:`.Dmrg` + % DMRG algorithm. + % + % mpo : :class:`.FiniteMpo` + % matrix product operator. + % + % mps : :class:`.FiniteMps` + % initial guess for MPS fixed point. + % + % envs : :class:`.FiniteEnvironment` + % initial guess for the environments. + % + % Returns + % ------- + % mps : :class:`.FiniteMps` + % MPS fixed point. + % + % envs : :class:`.FiniteEnvironment` + % corresponding environments. + % + % eta : :class:`double` + % final error measure at convergence. + arguments alg mpo diff --git a/src/algorithms/Expand.m b/src/algorithms/Expand.m index 2d19685..70056fb 100644 --- a/src/algorithms/Expand.m +++ b/src/algorithms/Expand.m @@ -1,5 +1,70 @@ classdef Expand % Bond expansion algorithm for uniform matrix product states. + % + % Properties + % ---------- + % bondsmethod : :class:`char` + % bond expansion method, options are: + % + % - :code:`'off'`: no bond expansion. + % - :code:`'factor'`: (default) multiply the bond dimsion in each sector by a fixed + % factor + % - :code:`'explicit'`: manually provide bond dimension expansion. + % - :code:`'extrapolate'`: extrapolate the bond dimension in each sector according to + % a pre-defined exponential distribution. + % - :code:`'twosite'`: expand bond dimension according to a truncated two-site update. + % + % chargesmethod : :class:`char` + % charge expansion method, options are: + % + % - :code:`'off'`: (default) no charge expansion. + % - :code:`'fusionproduct'`: expand virtual charges according to the fusion product of + % each previous virtual space with the corresponding physical space. + % - :code:`'twosite'`: expand virtual charges according to a truncated two-site + % update. + % + % schmidtcut : :class:`double` + % cut in singular values used in two-site update, defaults to :code:`1e-5`. + % + % notrunc : :class:`logical` + % disable truncation such that the bond dimension is only grown, defaults to + % :code:`false`. + % + % noisefactor : :class:`double` + % noise factor applied to expanded MPS entries in order to improve stability, defaults + % to :code:`1e-3`. + % + % which : :class:`char` + % eigenvalue selector used in two-site update routine (passed as the :code:`sigma` + % argument to :func:`.eigsolve`), defaults to :code:`'largestabs'`. + % + % minbond : :class:`int` + % minimal bond dimension in for each charge, defaults to :code:`1` + % + % maxbond : :class:`int` + % maximal bond dimension for each charge, defaults to :code:`1e9`. + % + % tolbond : :class:`double` + % tolerance on expanded bond dimension compared to their current values, defaults to + % :code:`0.2`. + % + % bondfactor : :class:`double` + % expansion factor used for the :code:`'factor'` bond expansion method, defaults to + % :code:`1.2`. + % + % cutfactor : :class:`double` + % cut factor used in bond dimension extrapolation for the :code:`'extrapolate'` bond + % expansion method, defaults to :code:`1`. + % + % explicitbonds : :class:`int` + % vector of integers indicating the bond dimsension to add/subtract for each charge, + % defaults to :code:`[]`. + % + % mincharges : :class:`int` + % minimal number of charges in eevery virtual space, defaults to :code:`2`. + % + % finalize : :class:`function_handle` + % optional finalization. %% Options properties @@ -48,7 +113,30 @@ end function [mps2, flag] = changebonds(alg, mpo, mps1) - % Change sectors and bond dimensions of mps virtual spaces. + % Change charges and bond dimensions of MPS virtual spaces. + % + % Usage + % ----- + % :code:`[mps2, flag] = changebonds(alg, mpo, mps1)` + % + % Arguments + % --------- + % alg : :class:`.Expand` + % bond expansion algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps1 : :class:`.UniformMps` + % MPS to be expanded. + % + % Returns + % ------- + % mps2 : :class:`.UniformMps` + % expanded MPS. + % + % flag : :class:`struct` + % explain. % canonicalize before starting for d = 1:depth(mps1) diff --git a/src/algorithms/IDmrg.m b/src/algorithms/IDmrg.m index e4d7863..9825268 100644 --- a/src/algorithms/IDmrg.m +++ b/src/algorithms/IDmrg.m @@ -1,5 +1,42 @@ classdef IDmrg - % Infinite Density Matrix Renormalization Group algorithm + % `Infinite Density Matrix Renormalization Group algorithm `_. + % + % Properties + % ---------- + % tol : :class:`double` + % tolerance for convergence criterion, defaults to :code:`1e-10`. + % + % miniter : :class:`int` + % minimum number of iteration, defaults to 5. + % + % maxiter : :class:`int` + % maximum number of iteration, defaults to 100. + % + % verbosity : :class:`.Verbosity` + % verbosity level of the algorithm, defaults to :code:`Verbosity.iter`. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. + % + % dynamical_tols : :class:`logical` + % indicate whether or not to use a dynamical tolerance scaling for the algorithm's + % subroutines based on the current error measure, defaults to :code:`false` + % + % tol_min : :class:`double` + % smallest allowed convergence tolerance for soubroutines, defaults to :code:`1e-12`. + % + % tol_max : :class:`double` + % highest allowed convergence tolerance for soubroutines, defaults to :code:`1e-6`. + % + % eigs_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the local + % update solver subroutine based on the current error measure, defaults to + % :code:`1e-4`. + % + % alg_eigs : :class:`.KrylovSchur` or :class:`.Arnoldi` + % algorithm used for the eigsolver subroutines, defaults to + % :code:`Arnoldi('MaxIter', 100, 'KrylovDim', 20)`. properties tol = 1e-10 @@ -40,6 +77,37 @@ end function [mps, lambda, GL, GR] = fixedpoint(alg, mpo, mps) + % Find the fixed point MPS of an infinite MPO, given an initial guess. + % + % Usage + % ----- + % :code:`[mps, lambda, GL, GR] = fixedpoint(alg, mpo, mps)` + % + % Arguments + % --------- + % alg : :class:`.IDmrg` + % IDMRG algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps : :class:`.UniformMps` + % initial guess for MPS fixed point. + % + % Returns + % ------- + % mps : :class:`.UniformMps` + % MPS fixed point. + % + % lambda : :class:`double` + % eigenvalue. + % + % GL : :class:`cell` of :class:`.MpsTensor` + % left environment tensors. + % + % GR : :class:`cell` of :class:`.MpsTensor` + % right environment tensors. + if period(mpo) ~= period(mps) error('idmrg:argerror', ... 'periodicity of mpo (%d) should be equal to that of the mps (%d)', ... diff --git a/src/algorithms/IDmrg2.m b/src/algorithms/IDmrg2.m index ba29758..5ae2264 100644 --- a/src/algorithms/IDmrg2.m +++ b/src/algorithms/IDmrg2.m @@ -1,5 +1,49 @@ classdef IDmrg2 - % Infinite Density Matrix Renormalization Group algorithm with 2-site updates. + % `Infinite Density Matrix Renormalization Group algorithm with 2-site updates `_. + % + % Properties + % ---------- + % tol : :class:`double` + % tolerance for convergence criterion, defaults to :code:`1e-10`. + % + % miniter : :class:`int` + % minimum number of iteration, defaults to 5. + % + % maxiter : :class:`int` + % maximum number of iteration, defaults to 100. + % + % verbosity : :class:`.Verbosity` + % verbosity level of the algorithm, defaults to :code:`Verbosity.iter`. + % + % doplot : :class:`logical` + % plot progress, defaults to :code:`false`. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. + % + % dynamical_tols : :class:`logical` + % indicate whether or not to use a dynamical tolerance scaling for the algorithm's + % subroutines based on the current error measure, defaults to :code:`false` + % + % tol_min : :class:`double` + % smallest allowed convergence tolerance for soubroutines, defaults to :code:`1e-12`. + % + % tol_max : :class:`double` + % highest allowed convergence tolerance for soubroutines, defaults to :code:`1e-6`. + % + % eigs_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the local + % update solver subroutine based on the current error measure, defaults to + % :code:`1e-7`. + % + % trunc : :class:`struct` + % truncation method for local 2-site update, see :meth:`.Tensor.tsvd` for details on + % truncation options. + % + % alg_eigs : :class:`.KrylovSchur` or :class:`.Arnoldi` + % algorithm used for the eigsolver subroutines, defaults to + % :code:`Arnoldi('MaxIter', 100, 'KrylovDim', 20)`. properties tol = 1e-10 @@ -50,6 +94,37 @@ end function [mps, lambda, GL, GR] = fixedpoint(alg, mpo, mps) + % Find the fixed point MPS of an infinite MPO, given an initial guess. + % + % Usage + % ----- + % :code:`[mps, lambda, GL, GR] = fixedpoint(alg, mpo, mps)` + % + % Arguments + % --------- + % alg : :class:`.IDmrg2` + % IDMRG2 algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps : :class:`.UniformMps` + % initial guess for MPS fixed point. + % + % Returns + % ------- + % mps : :class:`.UniformMps` + % MPS fixed point. + % + % lambda : :class:`double` + % eigenvalue. + % + % GL : :class:`cell` of :class:`.MpsTensor` + % left environment tensors. + % + % GR : :class:`cell` of :class:`.MpsTensor` + % right environment tensors. + if period(mpo) ~= period(mps) error('idmrg2:argerror', ... 'periodicity of mpo (%d) should be equal to that of the mps (%d)', ... diff --git a/src/algorithms/QPAnsatz.m b/src/algorithms/QPAnsatz.m index 5a59c98..056cc0f 100644 --- a/src/algorithms/QPAnsatz.m +++ b/src/algorithms/QPAnsatz.m @@ -1,5 +1,22 @@ classdef QPAnsatz - % Quasi-Particle excitation ansatz + % `Quasi-Particle excitation ansatz `_. + % + % Properties + % ---------- + % alg_eigs : :class:`.KrylovSchur` or :class:`.Arnoldi` + % algorithm used for the eigsolver subroutines, defaults to + % :code:`Arnoldi('MaxIter', 100, 'KrylovDim', 30, 'Tol', 1e-8)`. + % + % alg_environments : :class:`.struct` + % algorithm used for the environment subroutines (see :meth:`.AbstractTensor.linsolve` + % for details), defaults to :code:`struct('Tol', 1e-10, 'Algorithm', 'bicgstabl')`. + % + % howmany : :class:`int` + % number of excitations to compute. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. properties alg_eigs = Arnoldi('MaxIter', 100, 'KrylovDim', 30, 'Tol', 1e-8, 'Verbosity', Verbosity.diagnostics) @@ -29,6 +46,31 @@ end function [qp, mu] = excitations(alg, mpo, qp) + % Find excitations + % + % Usage + % ----- + % :code:`[qp, mu] = excitations(alg, mpo, qp)` + % + % Arguments + % --------- + % alg : :class:`.QPAnsatz` + % Quasi-particle ansatz algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps : :class:`.UniformMps` + % initial guess for MPS fixed point. + % + % Returns + % ------- + % qp : :class:`.InfQP` + % vector of quasiparticle states. + % + % mu : :class:`double` + % vector of corresponding eigenvalues. + if period(mpo) ~= period(qp) error('QPAnsatz:argerror', ... 'periodicity of mpo (%d) should be equal to that of the mps (%d)', ... diff --git a/src/algorithms/Vomps.m b/src/algorithms/Vomps.m index 01fe23e..05ddcb1 100644 --- a/src/algorithms/Vomps.m +++ b/src/algorithms/Vomps.m @@ -1,6 +1,64 @@ classdef Vomps - % Fixed point algorithm for maximizing overlap. - + % `Fixed point algorithm for maximizing overlap `_. + % + % Properties + % ---------- + % tol : :class:`double` + % tolerance for convergence criterion, defaults to :code:`1e-10`. + % + % miniter : :class:`int` + % minimum number of iteration, defaults to 5. + % + % maxiter : :class:`int` + % maximum number of iteration, defaults to 100. + % + % verbosity : :class:`.Verbosity` + % verbosity level of the algorithm, defaults to :code:`Verbosity.iter`. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. + % + % dynamical_tols : :class:`logical` + % indicate whether or not to use a dynamical tolerance scaling for the algorithm's + % subroutines based on the current error measure, defaults to :code:`true` + % + % tol_min : :class:`double` + % smallest allowed convergence tolerance for soubroutines, defaults to :code:`1e-12`. + % + % tol_max : :class:`double` + % highest allowed convergence tolerance for soubroutines, defaults to :code:`1e-6`. + % + % eigs_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the local + % update solver subroutine based on the current error measure, defaults to + % :code:`1e-4`. + % + % canonical_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the + % canonicalization subroutine based on the current error measure, defaults to + % :code:`1e-8`. + % + % environments_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the environment + % solver subroutine based on the current error measure, defaults to :code:`1e-4`. + % + % multiAC : :class:`char` + % execution style for the local `AC` updates for a multi-site unit cell, options are: + % + % - :code:`'parallel'`: (default) update all `AC` tensors simultaneously. + % - :code:`'sequential'`: update one `AC` tensor at a time, sweeping through the unit + % cell. + % + % dynamical_multiAC : :class:`logical` + % automatically switch from :code:`'sequential'` to :code:`'parallel'` if the error + % measure becomes small enough, defaults to :code:`false`. + % + % tol_multiAC : :class:`char` + % tolerance for automatically switching from :code:`'sequential'` to + % :code:`'parallel'` if the error measure falls below this value, defaults to + % :code:`Inf`. + %% Options properties tol = 1e-5 @@ -51,6 +109,38 @@ end function [mps2, GL, GR] = approximate(alg, mpo, mps1, mps2) + % Approximate the product of an MPS and an MPO as an MPS. + % + % Usage + % ----- + % :code:`[mps2, GL, GR] = approximate(alg, mpo, mps1, mps2)` + % + % Arguments + % --------- + % alg : :class:`.Vumps` + % VUMPS algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps1 : :class:`.UniformMps` + % MPS to which the MPO is applied. + % + % mps2 : :class:`.UniformMps` + % initial guess for MPS approximation. + % + % Returns + % ------- + % mps2 : :class:`.UniformMps` + % MPS approximation, such that :code:`mps2` :math:`\approx` + % :code:`mpo * mps1`. + % + % GL : :class:`cell` of :class:`.MpsTensor` + % left environment tensors. + % + % GR : :class:`cell` of :class:`.MpsTensor` + % right environment tensors. + if period(mpo) ~= period(mps1) || period(mpo) ~= period(mps2) error('vumps:argerror', ... 'periodicitys should match: mpo (%d), mps1 (%d), mps2(%d)', ... diff --git a/src/algorithms/Vumps.m b/src/algorithms/Vumps.m index 4d0010f..0a745f3 100644 --- a/src/algorithms/Vumps.m +++ b/src/algorithms/Vumps.m @@ -1,6 +1,71 @@ classdef Vumps < handle - % Variational fixed point algorithm for uniform matrix product states. - + % `Variational fixed point algorithm for uniform matrix product states `_. + % + % Properties + % ---------- + % tol : :class:`double` + % tolerance for convergence criterion, defaults to :code:`1e-10`. + % + % miniter : :class:`int` + % minimum number of iteration, defaults to :code:`5`. + % + % maxiter : :class:`int` + % maximum number of iteration, defaults to code:`100`. + % + % verbosity : :class:`.Verbosity` + % verbosity level of the algorithm, defaults to :code:`Verbosity.iter`. + % + % doplot : :class:`logical` + % plot progress, defaults to :code:`false`. + % + % which : :class:`char` + % eigenvalue selector (passed as the :code:`sigma` argument to :func:`.eigsolve`), + % defaults to :code:`'largestabs'`. + % + % dynamical_tols : :class:`logical` + % indicate whether or not to use a dynamical tolerance scaling for the algorithm's + % subroutines based on the current error measure, defaults to :code:`true` + % + % tol_min : :class:`double` + % smallest allowed convergence tolerance for soubroutines, defaults to :code:`1e-12`. + % + % tol_max : :class:`double` + % highest allowed convergence tolerance for soubroutines, defaults to :code:`1e-10`. + % + % eigs_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the local + % update solver subroutine based on the current error measure, defaults to + % :code:`1e-6`. + % + % canonical_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the + % canonicalization subroutine based on the current error measure, defaults to + % :code:`1e-8`. + % + % environments_tolfactor : :class:`double` + % relative scaling factor for determining the convergence tolerance of the environment + % solver subroutine based on the current error measure, defaults to :code:`1e-6`. + % + % multiAC : :class:`char` + % execution style for the local `AC` updates for a multi-site unit cell, options are: + % + % - :code:`'parallel'`: (default) update all `AC` tensors simultaneously. + % - :code:`'sequential'`: update one `AC` tensor at a time, sweeping through the unit + % cell. + % + % dynamical_multiAC : :class:`logical` + % automatically switch from :code:`'sequential'` to :code:`'parallel'` if the error + % measure becomes small enough, defaults to :code:`false`. + % + % tol_multiAC : :class:`char` + % tolerance for automatically switching from :code:`'sequential'` to + % :code:`'parallel'` if the error measure falls below this value, defaults to + % :code:`Inf`. + % + % alg_eigs : :class:`.KrylovSchur` or :class:`.Arnoldi` + % algorithm used for the eigsolver subroutines, defaults to + % :code:`Arnoldi('MaxIter', 100, 'KrylovDim', 20)`. + %% Options properties tol = 1e-10 @@ -73,6 +138,39 @@ end function [mps, lambda, GL, GR, eta] = fixedpoint(alg, mpo, mps) + % Find the fixed point MPS of an infinite MPO, given an initial guess. + % + % Usage + % ----- + % :code:`[mps, lambda, GL, GR, eta] = fixedpoint(alg, mpo, mps)` + % + % Arguments + % --------- + % alg : :class:`.Vumps` + % VUMPS algorithm. + % + % mpo : :class:`.InfMpo` + % matrix product operator. + % + % mps : :class:`.UniformMps` + % initial guess for MPS fixed point. + % + % Returns + % ------- + % mps : :class:`.UniformMps` + % MPS fixed point. + % + % lambda : :class:`double` + % eigenvalue. + % + % GL : :class:`cell` of :class:`.MpsTensor` + % left environment tensors. + % + % GR : :class:`cell` of :class:`.MpsTensor` + % right environment tensors. + % + % eta : :class:`double` + % final error measure at convergence. if period(mpo) ~= period(mps) error('vumps:argerror', ... diff --git a/src/algorithms/eigsolvers/Arnoldi.m b/src/algorithms/eigsolvers/Arnoldi.m index 2902bb7..e04f6eb 100644 --- a/src/algorithms/eigsolvers/Arnoldi.m +++ b/src/algorithms/eigsolvers/Arnoldi.m @@ -1,14 +1,37 @@ classdef Arnoldi % Arnoldi Krylov algorithm for linear algebra problems. + % + % Properties + % ---------- + % tol : :class:`double` + % convergence tolerance, defaults to :code:`1e-10`. + % + % maxiter : :class:`int` + % maximum number of iterations, defaults to :code:`100`. + % + % krylovdim : :class:`int` + % Krylov subspace dimension, defaults to :code:`20`. + % + % deflatedim : :class:`int` + % number of Krylov vectors to keep when deflating. + % + % reorth : :class:`int` + % reorthogonalize basis if larger than this number, defaults to :code:`20`. + % + % nobuild : :class:`int` + % frequency of convergence check when building, defaults to :code:`3`. + % + % verbosity : :class:`.Verbosity` + % display information, defaults to :code:`Verbosity.warn`. properties - tol = 1e-10 % convergence tolerance - maxiter = 100 % maximum iterations - krylovdim = 20 % Krylov subspace dimension - deflatedim % number of Krylov vectors to keep when deflating - reorth = 20 % reorthogonalize basis if larger than this number - nobuild = 3 % frequency of convergence check when building - verbosity = Verbosity.warn % display information + tol = 1e-10 + maxiter = 100 + krylovdim = 20 + deflatedim + reorth = 20 + nobuild = 3 + verbosity = Verbosity.warn end methods @@ -31,26 +54,27 @@ % Usage % ----- % :code:`[V, D, flag] = eigsolve(A, v, howmany, sigma)` + % % :code:`D = eigsolve(A, v, ...)` % % Arguments % --------- - % A : matrix or function_handle + % A : :class:`matrix` or :class:`function_handle` % A square matrix. % A function handle which implements one of the following, depending on sigma: % - % - A \ x, if `sigma` is 0 or 'smallestabs' - % - (A - sigma * I) \ x, if sigma is a nonzero scalar - % - A * x, for all other cases + % - :code:`A \ x`, if `sigma` is 0 or 'smallestabs' + % - :code:`(A - sigma * I) \ x`, if sigma is a nonzero scalar + % - :code:`A * x`, for all other cases % - % v : vector + % v : :class:`vector` % initial guess for the eigenvector. % - % howmany : int + % howmany : :class:`int` % amount of eigenvalues and eigenvectors that should be computed. By default % this is 1, and this should not be larger than the total dimension of A. % - % sigma : `char` or numeric + % sigma : :class:`char` or numeric % selector for the eigenvalues, should be either one of the following: % % - 'largestabs', 'lm': default, eigenvalues of largest magnitude @@ -59,17 +83,20 @@ % - 'smallestabs', 'sm': default, eigenvalues of smallest magnitude % - 'smallestreal', 'sr': eigenvalues with smallest real part % - 'smallestimag', 'si': eigenvalues with smallest imaginary part. + % - numeric : eigenvalues closest to sigma. % % Returns % ------- - % V : (1, howmany) array + % V : (1, howmany) :class:`vector` % vector of eigenvectors. % - % D : numeric + % D : :class:`numeric` % vector of eigenvalues if only a single output argument is asked, diagonal % matrix of eigenvalues otherwise. % - % flag : int + % flag : :class:`int` + % convergence info flag: + % % - flag = 0: all eigenvalues are converged. % - flag = 1: invariant subspace was found and the algorithm was aborted. % - flag = 2: algorithm did not converge after maximum number of iterations. diff --git a/src/algorithms/eigsolvers/KrylovSchur.m b/src/algorithms/eigsolvers/KrylovSchur.m index bce97ee..c1a4581 100644 --- a/src/algorithms/eigsolvers/KrylovSchur.m +++ b/src/algorithms/eigsolvers/KrylovSchur.m @@ -1,11 +1,25 @@ classdef KrylovSchur % KrylovSchur wrapper for Matlab implementation of eigs + % + % Properties + % ---------- + % tol : :class:`double` + % convergence tolerance, defaults to :code:`1e-10`. + % + % maxiter : :class:`int` + % maximum number of iterations, defaults to :code:`100`. + % + % krylovdim : :class:`int` + % Krylov subspace dimension, defaults to :code:`20`. + % + % verbosity : :class:`.Verbosity` + % display information, defaults to :code:`Verbosity.warn`. properties - tol = 1e-10 % convergence tolerance - maxiter = 100 % maximum iterations - krylovdim = 20 % Krylov subspace dimension - verbosity = Verbosity.warn % display information + tol = 1e-10 + maxiter = 100 + krylovdim = 20 + verbosity = Verbosity.warn end methods @@ -28,26 +42,27 @@ % Usage % ----- % :code:`[V, D, flag] = eigsolve(A, v, howmany, sigma, kwargs)` + % % :code:`D = eigsolve(A, v, ...)` % % Arguments % --------- - % A : matrix or function_handle + % A : :class:`matrix` or :class:`function_handle` % A square matrix. % A function handle which implements one of the following, depending on sigma: % - % - A \ x, if `sigma` is 0 or 'smallestabs' - % - (A - sigma * I) \ x, if sigma is a nonzero scalar - % - A * x, for all other cases + % - :code:`A \ x`, if :code:`sigma` is 0 or 'smallestabs' + % - :code:(A - sigma * I) \ x`, if sigma is a nonzero scalar + % - :code:A * x`, for all other cases % - % v : vector + % v : :class:`vector` % initial guess for the eigenvector. % - % howmany : int + % howmany : :class:`int` % amount of eigenvalues and eigenvectors that should be computed. By default % this is 1, and this should not be larger than the total dimension of A. % - % sigma : `char` or numeric + % sigma : :class:`char` or :class:`numeric` % selector for the eigenvalues, should be either one of the following: % % - 'largestabs', 'lm': default, eigenvalues of largest magnitude @@ -56,28 +71,26 @@ % - 'smallestabs', 'sm': default, eigenvalues of smallest magnitude % - 'smallestreal', 'sr': eigenvalues with smallest real part % - 'smallestimag', 'si': eigenvalues with smallest imaginary part. - % - 'bothendsreal', 'be': both ends, with howmany/2 values with largest and - % smallest real part respectively. - % - 'bothendsimag', 'li': both ends, with howmany/2 values with largest and - % smallest imaginary part respectively. % - numeric : eigenvalues closest to sigma. % % Keyword Arguments % ----------------- - % IsSymmetric : logical + % IsSymmetric : :class:`logical` % flag to speed up the algorithm if the operator is symmetric, false by % default. % % Returns % ------- - % V : (1, howmany) array + % V : (1, howmany) :class:`vector` % vector of eigenvectors. % - % D : numeric + % D : :class:`numeric` % vector of eigenvalues if only a single output argument is asked, diagonal % matrix of eigenvalues otherwise. % - % flag : int + % flag : :class:`int` + % convergence info flag: + % % if flag = 0 then all eigenvalues are converged, otherwise not. arguments diff --git a/src/caches/DLL.m b/src/caches/DLL.m index 0c3a775..b562d76 100644 --- a/src/caches/DLL.m +++ b/src/caches/DLL.m @@ -4,10 +4,15 @@ % % Based on the work by Richard Lange (2022). Least-Recently Used (LRU) Cache % (https://www.mathworks.com/matlabcentral/fileexchange/68836-least-recently-used-lru-cache), - % MATLAB Central File Exchange. Retrieved June 18, 2022. + % MATLAB Central File Exchange. Retrieved June 18, 2022. + % + % Properties + % ---------- + % val : :class:`any` + % data stored in this element properties - val % data stored in this element + val end properties (Access = private) @@ -22,12 +27,12 @@ % % Arguments % --------- - % val : any + % val : :class:`any` % data stored in this element. % % Returns % ------- - % dll : :class:`DLL` + % dll : :class:`.DLL` % data wrapped in a doubly-linked list format. obj.val = val; @@ -41,12 +46,12 @@ % % Arguments % --------- - % obj : :class:`DLL` + % obj : :class:`.DLL` % object to remove from the list. % % Returns % ------- - % obj : :class:`DLL` + % obj : :class:`.DLL` % removed object, with detached links. obj.prev.next = obj.next; @@ -60,15 +65,15 @@ % % Arguments % --------- - % obj : :class:`DLL` + % obj : :class:`.DLL` % list to append to. % - % other : :class:`DLL` + % other : :class:`.DLL` % object to append. % % Returns % ------- - % obj : :class:`DLL` + % obj : :class:`.DLL` % updated list. other.next = obj.next; @@ -88,12 +93,12 @@ % % Arguments % --------- - % obj : :class`DLL` + % obj : :class`.DLL` % current element in the list. % % Returns % ------- - % other : :class`DLL` + % other : :class`.DLL` % next element in the list. other = obj.next; @@ -110,12 +115,12 @@ % % Arguments % --------- - % obj : :class`DLL` + % obj : :class`.DLL` % current element in the list. % % Returns % ------- - % other : :class`DLL` + % other : :class`.DLL` % previous element in the list. other = obj.prev; diff --git a/src/caches/GetMD5/GetMD5.m b/src/caches/GetMD5/GetMD5.m index 993afd1..2da3a08 100644 --- a/src/caches/GetMD5/GetMD5.m +++ b/src/caches/GetMD5/GetMD5.m @@ -22,7 +22,7 @@ function GetMD5(varargin) % - 'Array' : Include the class and size information of `data` in the MD5 sum. This can be % applied for (nested) structs, objects, cells and sparse arrays also. % -% Format : char +% Format : :code:`char` % Format of the output, default value is 'hex'. % % - 'hex' : (1, 32) lowercase hexadecimal char. @@ -38,7 +38,7 @@ function GetMD5(varargin) % % Notes % ----- -% For sparse arrays, function handles, java and user-defined objects :func:`GetMD5_helper` +% For sparse arrays, function handles, java and user-defined objects :func:`.GetMD5_helper` % is called to convert into a data format that can be handled. % % The C-Mex-file is compiled automatically when this function is called for the first time. diff --git a/src/caches/GetMD5/GetMD5_helper.m b/src/caches/GetMD5/GetMD5_helper.m index b0083b6..a4da9c7 100644 --- a/src/caches/GetMD5/GetMD5_helper.m +++ b/src/caches/GetMD5/GetMD5_helper.m @@ -1,5 +1,5 @@ function S = GetMD5_helper(V) -% GetMD5_helper: Convert non-elementary array types for GetMD5 +% Convert non-elementary array types for GetMD5 % The C-Mex function GetMD5 calls this function to obtain meaningful unique data % for function handles, java or user-defined objects and sparse arrays. The % applied processing can depend on the needs of the users, therefore it is diff --git a/src/caches/GetMD5/InstallMex.m b/src/caches/GetMD5/InstallMex.m index f360e59..dd3d139 100644 --- a/src/caches/GetMD5/InstallMex.m +++ b/src/caches/GetMD5/InstallMex.m @@ -1,5 +1,5 @@ function Ok = InstallMex(SourceFile, varargin) -% INSTALLMEX - Compile and install Mex file +% Compile and install Mex file % The C, C++ or FORTRAN mex file is compiled and additional installation % routines are started. Advanced users can call MEX() manually instead, but some % beginners are overwhelmed by instructions for a compilation sometimes. @@ -52,9 +52,13 @@ % -------- % % Compile func1.c with LAPACK libraries: -% InstallMex('func1', {'libmwlapack.lib', 'libmwblas.lib'}) +% +% :code:`InstallMex('func1', {'libmwlapack.lib', 'libmwblas.lib'})` +% % Compile func2.cpp, enable debugging and call a test function: -% InstallMex('func2.cpp', '-debug', 'Test_func2'); +% +% :code:`InstallMex('func2.cpp', '-debug', 'Test_func2');` +% % These commands can be appended after the help section of an M-file, when the % compilation should be started automatically, if the compiled MEX is not found. % diff --git a/src/caches/GetMD5/uTest_GetMD5.m b/src/caches/GetMD5/uTest_GetMD5.m index 2313b32..da1f286 100644 --- a/src/caches/GetMD5/uTest_GetMD5.m +++ b/src/caches/GetMD5/uTest_GetMD5.m @@ -10,8 +10,8 @@ function uTest_GetMD5(doSpeed) % Arguments % --------- % doSpeed -% Optional logical flag to trigger time consuming speed tests. Defaults to :code:`true.If -% no speed test is defined, this is ignored. +% Optional logical flag to trigger time consuming speed tests. Defaults to :code:`true`. +% If no speed test is defined, this is ignored. % % Note % ---- diff --git a/src/caches/LRU.m b/src/caches/LRU.m index bf985c8..8ccc726 100644 --- a/src/caches/LRU.m +++ b/src/caches/LRU.m @@ -1,14 +1,31 @@ classdef LRU < handle - % LRU a least-recently-used cache. Stores data up to a preset memory limit, then removes + % A least-recently-used cache. Stores data up to a preset memory limit, then removes % the least-recently-used elements to free up space for additional data. + % + % Properties + % ---------- + % sentinel : :class:`.DLL` + % sentinel of DLL, +sentinel is MRU, -sentinel is LRU + % + % map : :class:`containers.Map` + % map of key --> dll + % + % itemlimit : :class:`int` + % maximum size of cache in number of items + % + % memlimit : :class:`double` + % maximum size of cache in bytes + % + % mem : :class:`double` + % current memory usage in bytes. properties (Access = private) - sentinel % sentinel of DLL, +sentinel is MRU, -sentinel is LRU - map % map of key --> dll - itemlimit = Inf % maximum size of cache in number of items - memlimit = 20 * 2^30 % maximum size of cache in bytes - mem = 0; % current memory usage in bytes. + sentinel + map + itemlimit = Inf + memlimit = 20 * 2^30 + mem = 0; end methods function cache = LRU(itemlimit, memlimit) @@ -16,15 +33,15 @@ % % Arguments % --------- - % itemlimit : int + % itemlimit : :class:`int` % maximum size of cache in number of items. % - % memlimit : numeric + % memlimit : :class:`double` % maximum size of cache in number of bytes. % % Returns % ------- - % cache : :class:`LRU` + % cache : :class:`.LRU` % empty LRU cache. % Initialize data @@ -45,15 +62,15 @@ % % Arguments % --------- - % cache : :class:`LRU` + % cache : :class:`.LRU` % data cache. % - % key : :class:`uint8` + % key : :class:`.uint8` % data key. % % Returns % ------- - % val : any + % val : :class:`any` % value that is stored with a key, or empty if key not in cache. if isKey(cache.map, key) @@ -73,18 +90,18 @@ % % Arguments % --------- - % cache : :class:`LRU` + % cache : :class:`.LRU` % data cache. % % key : :class:`uint8` % data key. % - % val : any + % val : :class:`any` % data value. % % Returns % ------- - % cache : :class:`LRU` + % cache : :class:`.LRU` % updated cache. % remove previously stored data diff --git a/src/environments/FiniteEnvironment.m b/src/environments/FiniteEnvironment.m index 9304f35..71e7f72 100644 --- a/src/environments/FiniteEnvironment.m +++ b/src/environments/FiniteEnvironment.m @@ -1,6 +1,17 @@ classdef FiniteEnvironment - %FINITEENVIRONMENT Summary of this class goes here - % Detailed explanation goes here + % Data structure for managing the environments in finite MPS algorithms. + % + % Properties + % ---------- + % GL : :class:`cell` of :class:`.MpsTensor` + % environment tensors corresponding to the left-gauged part of the MPS. + % + % GR : :class:`cell` of :class:`.MpsTensor` + % environment tensors corresponding to the right-gauged part of the MPS. + % + % Todo + % ---- + % Document properties GL @@ -9,8 +20,6 @@ methods function envs = FiniteEnvironment(varargin) - %FINITEENVIRONMENT Construct an instance of this class - % Detailed explanation goes here if nargin == 0, return; end if nargin == 2 envs.GL = varargin{1}; diff --git a/src/models/fermionoperators/c_min.m b/src/models/fermionoperators/c_min.m index 2e04c81..4851bda 100644 --- a/src/models/fermionoperators/c_min.m +++ b/src/models/fermionoperators/c_min.m @@ -1,4 +1,15 @@ function c = c_min(kwargs) +% Fermionic annihilation operator. +% +% Keyword arguments +% ----------------- +% 'Side' : :class:`char` +% side, 'left or 'right'. +% +% Returns +% c : :class:`.Tensor` +% annihilation operator represented as a 3-leg tensor with :math:`fZ_2` symmetry. + arguments kwargs.side = 'left' end diff --git a/src/models/fermionoperators/c_number.m b/src/models/fermionoperators/c_number.m index b6e1a28..03a1edc 100644 --- a/src/models/fermionoperators/c_number.m +++ b/src/models/fermionoperators/c_number.m @@ -1,4 +1,10 @@ function n = c_number() +% Fermionic number operator. +% +% Returns +% ------- +% n : :class:`.Tensor` +% number operator represented as a 2-leg tensor with :math:`fZ_2` symmetry. pspace = fZ2Space([0 1], [1 1], false); diff --git a/src/models/fermionoperators/c_plus.m b/src/models/fermionoperators/c_plus.m index 795df05..28a8cc8 100644 --- a/src/models/fermionoperators/c_plus.m +++ b/src/models/fermionoperators/c_plus.m @@ -1,4 +1,15 @@ function c_dagger = c_plus(kwargs) +% Fermionic creation operator. +% +% Keyword arguments +% ----------------- +% 'Side' : :class:`char` +% side, 'left or 'right'. +% +% Returns +% c_dagger : :class:`.Tensor` +% creation operator represented as a 3-leg tensor with :math:`fZ_2` symmetry. + arguments kwargs.side = 'left' end diff --git a/src/models/quantum1dHeisenberg.m b/src/models/quantum1dHeisenberg.m index b8a6dd8..e2ee882 100644 --- a/src/models/quantum1dHeisenberg.m +++ b/src/models/quantum1dHeisenberg.m @@ -1,10 +1,37 @@ function mpo = quantum1dHeisenberg(kwargs) +% Hamiltonian for the 1D Heisenberg model. +% +% .. math:: +% H = J \sum_{\langle ij \rangle} \vec{S}_i \cdot \vec{S}_j + h \sum_{i} S_i^z +% +% Keyword arguments +% ----------------- +% 'Spin' : :class:`double` +% halfinteger or integer spin label, defaults to :code:`1`. +% +% 'J' : :class:`double` +% exchange coupling, defaults to :code:`1`. +% +% 'h' : :class:`double` +% magnetic field, defaults to :code:`0`. +% +% 'L' : :class:`int` +% system size, defaults to :code:`Inf`. +% +% 'Symmetry' : :class:`char` +% symmetry group ('U1' or 'SU2'), defaults to :code:`'SU2'`. +% +% Returns +% ------- +% mpo : :class:`.InfJMpo` +% Heisenberg Hamiltonian as a Jordan block MPO. + arguments kwargs.Spin = 1 kwargs.J = 1 kwargs.h = 0 kwargs.L = Inf % size of system - kwargs.Symmetry {mustBeMember(kwargs.Symmetry, {'Z1', 'U1', 'SU2'})} = 'Z1' + kwargs.Symmetry {mustBeMember(kwargs.Symmetry, {'Z1', 'U1', 'SU2'})} = 'SU2' end J = kwargs.J; diff --git a/src/models/quantum1dHubbard.m b/src/models/quantum1dHubbard.m index a7c8cf1..85a2bac 100644 --- a/src/models/quantum1dHubbard.m +++ b/src/models/quantum1dHubbard.m @@ -1,10 +1,29 @@ function mpo = quantum1dHubbard(u, mu, kwargs) % Hamiltonian for the 1D Hubbard model. % -% `math`:-\sum (c^+_i c_j + c^+_j c_i) + u\sum (1 - 2n_{up}) * (1-2n_{down}) - mu\sum (n_{up} + n_{down}): +% .. math:: +% H = -\sum_{\langle ij \rangle} (c^+_i c_j + c^+_j c_i) + u \sum_i (1 - 2n_i^{\uparrow}) \cdot (1-2n_i^{\downarrow}) - \mu \sum_i (n_i^{\uparrow} + n_i^{\downarrow}) % % Arguments % --------- +% u : :class:`double` +% interaction strength. +% +% mu : :class:`double` +% chemical potential. +% +% Keyword arguments +% ----------------- +% 'Filling' : :class:`double` +% rational filling factor. +% +% 'Symmetry' : :class:`char` +% symmetry group, defaults to :code:`'fZ2xSU2xU1'`. +% +% Returns +% ------- +% mpo : :class:`.InfJMpo` +% Hubbard Hamiltonian as a Jordan block MPO. arguments u diff --git a/src/models/quantum1dIsing.m b/src/models/quantum1dIsing.m index 3c06b59..3c83a8c 100644 --- a/src/models/quantum1dIsing.m +++ b/src/models/quantum1dIsing.m @@ -1,4 +1,28 @@ function mpo = quantum1dIsing(kwargs) +% Hamiltonian for the 1D transverse-field Ising model. +% +% .. math:: +% H = -J \left(\sum_{\langle ij \rangle} S_i^x S_j^x + h \sum_{i} S_i^z \right). +% +% Keyword arguments +% ----------------- +% 'J' : :class:`double` +% :math:`ZZ` coupling, defaults to :code:`1`. +% +% 'h' : :class:`double` +% relative transverse field strength, defaults to :code:`1`. +% +% 'L' : :class:`int` +% system size, defaults to :code:`Inf`. +% +% 'Symmetry' : :class:`char` +% symmetry group ('Z1', 'Z2' or 'fZ2'), defaults to :code:`'Z1'`. +% +% Returns +% ------- +% mpo : :class:`.InfJMpo` +% Ising Hamiltonian as a Jordan block MPO. + arguments kwargs.J = 1 kwargs.h = 1 diff --git a/src/models/spinoperators/sigma_exchange.m b/src/models/spinoperators/sigma_exchange.m index 80150e6..2ca4b3c 100644 --- a/src/models/spinoperators/sigma_exchange.m +++ b/src/models/spinoperators/sigma_exchange.m @@ -1,4 +1,18 @@ function S = sigma_exchange(spin, symmetry) +% Spin exchange operator. +% +% Arguments +% --------- +% spin : :class:`double` +% halfinteger or integer spin label, defaults to :code:`1/2`. +% +% symmetry : :class:`char` +% symmetry group ('Z1' or 'SU2'), defaults to :code:`'SU2'`. +% +% Returns +% S : :class:`.Tensor` +% two-site exchange interaction represented as a 4-leg tensor. + arguments spin = 1/2 symmetry = 'Z1' diff --git a/src/models/spinoperators/sigma_min.m b/src/models/spinoperators/sigma_min.m index eb2a59a..87aaa23 100644 --- a/src/models/spinoperators/sigma_min.m +++ b/src/models/spinoperators/sigma_min.m @@ -1,4 +1,18 @@ function S = sigma_min(spin, symmetry) +% Spin lowering operator. +% +% Arguments +% --------- +% spin : :class:`double` +% halfinteger or integer spin label, defaults to :code:`1/2`. +% +% symmetry : :class:`char` +% symmetry group ('Z1' or 'U1'), defaults to :code:`'Z1'`. +% +% Returns +% S : :class:`.Tensor` +% lowering operator represented as a 3-leg tensor. + arguments spin = 1/2 symmetry = 'Z1' diff --git a/src/models/spinoperators/sigma_plus.m b/src/models/spinoperators/sigma_plus.m index e7d907c..55c5617 100644 --- a/src/models/spinoperators/sigma_plus.m +++ b/src/models/spinoperators/sigma_plus.m @@ -1,4 +1,18 @@ function S = sigma_plus(spin, symmetry) +% Spin raising operator. +% +% Arguments +% --------- +% spin : :class:`double` +% halfinteger or integer spin label, defaults to :code:`1/2`. +% +% symmetry : :class:`char` +% symmetry group ('Z1' or 'U1'), defaults to :code:`'Z1'`. +% +% Returns +% S : :class:`.Tensor` +% raising operator represented as a 3-leg tensor. + arguments spin = 1/2 symmetry = 'Z1' diff --git a/src/models/statmech2dIsing.m b/src/models/statmech2dIsing.m index 58470ca..ee0f13c 100644 --- a/src/models/statmech2dIsing.m +++ b/src/models/statmech2dIsing.m @@ -1,4 +1,24 @@ function O = statmech2dIsing(kwargs) +% MPO encoding the transfer matrix of the partition function of the 2D classical Ising model +% +% .. math:: +% \mathcal{Z} = \sum_{\{s\}} \prod_{\langle ij \rangle} \exp \left( \beta s_i s_j \right). +% +% Keyword arguments +% ----------------- +% 'beta' : :class:`double` +% inverse temperature. +% +% 'L' : :class:`int` +% system size, defaults to :code:`Inf`. +% +% 'Symmetry' : :class:`char` +% symmetry group ('Z1', 'Z2'), defaults to :code:`'Z1'`. +% +% Returns +% ------- +% mpo : :class:`.InfMpo` or :class:`.Finite` +% MPO transfer matrix of the Ising partition function. arguments kwargs.beta = log(1 + sqrt(2)) / 2; diff --git a/src/mps/FiniteMpo.m b/src/mps/FiniteMpo.m index a1b870f..ce18dca 100644 --- a/src/mps/FiniteMpo.m +++ b/src/mps/FiniteMpo.m @@ -1,5 +1,20 @@ classdef FiniteMpo - % Finite Matrix product operators + % Finite matrix product operator. + % + % Properties + % ---------- + % L : :class:`.MpsTensor` + % left end tensor. + % + % O : :class:`cell` of :class:`.MpoTensor` or :class:`.PepsSandwich` + % bulk MPO tensors. + % + % R : :class:`.MpsTensor` + % right end tensor. + % + % Todo + % ---- + % Document. properties L MpsTensor @@ -60,7 +75,7 @@ end function v = initialize_fixedpoint(mpo) - % Initialize a dense tensor for the fixedpoint of a :class:`FiniteMPO`. + % Initialize a dense tensor for the fixedpoint of a :class:`.FiniteMPO`. N = prod(cellfun(@(x) size(x, 4), mpo.O)); for i = N:-1:1 @@ -100,7 +115,7 @@ end function T = transfermatrix(mpo, mps1, mps2, sites) - arguments + arguments mpo mps1 mps2 = mps1 diff --git a/src/mps/FiniteMps.m b/src/mps/FiniteMps.m index 46d4754..1eeaeb2 100644 --- a/src/mps/FiniteMps.m +++ b/src/mps/FiniteMps.m @@ -1,5 +1,18 @@ classdef FiniteMps - % Finite Matrix product states + % Finite matrix product state. + % + % Properties + % ---------- + % A : :class:`cell` of :class:`.MpsTensor` + % set of tensors that define a finite MPS. + % + % center : :class:`int` + % location of center gauge, such that every tensor to the left (right) of + % :code:`center` is in left (right) gauge. + % + % Todo + % ---- + % Document. properties A (1,:) cell diff --git a/src/mps/InfJMpo.m b/src/mps/InfJMpo.m index 935efa6..06b820c 100644 --- a/src/mps/InfJMpo.m +++ b/src/mps/InfJMpo.m @@ -1,5 +1,9 @@ classdef InfJMpo < InfMpo - % Infinite Mpo with a Jordan block structure + % Infinite translation invariant matrix product operator with a Jordan block structure. + % + % Todo + % ---- + % Document. methods function mpo = InfJMpo(varargin) diff --git a/src/mps/InfMpo.m b/src/mps/InfMpo.m index 7286073..b31579d 100644 --- a/src/mps/InfMpo.m +++ b/src/mps/InfMpo.m @@ -1,5 +1,14 @@ classdef InfMpo % Infinite translation invariant matrix product operator. + % + % Properties + % ---------- + % O : :class:`cell` of :class:`.MpoTensor` or :class:`.PepsSandwich` + % cell of MPO tensors in translation invariant unit cell. + % + % Todo + % ---- + % Document properties O diff --git a/src/mps/InfQP.m b/src/mps/InfQP.m index 170bf57..918ab25 100644 --- a/src/mps/InfQP.m +++ b/src/mps/InfQP.m @@ -1,5 +1,9 @@ classdef InfQP % Infinite Quasi-Particle states + % + % Todo + % ---- + % Document. %% Properties @@ -240,24 +244,24 @@ end function rho = fixedpoint(qp, type, w) - % compute the fixed point of the transfer matrix of an mps. + % compute the fixed point of the transfer matrix of a quasi-particle state. % % Usage % ----- - % :code:`rho = fixedpoint(mps, type, w)` + % :code:`rho = fixedpoint(qp, type, w)` % % Arguments % --------- - % mps : :class:`UniformMps` - % input state. + % mps : :class:`.InfQP` + % input quasi-particle state. % - % type : char + % type : :class:`char` % specification of the type of transfer matrix: % general format: sprintf(%c_%c%c, side, top, bot) where side is 'l' or 'r' to % determine which fixedpoint, and top and bot are 'L' or 'R' to specify % whether to use AL or AR in the transfer matrix. % - % w : integer + % w : :class:`int` % position within the mps unitcell of the fixed point. arguments @@ -287,16 +291,16 @@ % % Arguments % --------- - % qp : :class:`InfQP` + % qp : :class:`.InfQP` % input quasi-particle state. % - % type : 'real' or 'complex' + % type : :class:`char`, 'real' or 'complex' % optionally specify if complex entries should be seen as 1 or 2 parameters. % Defaults to 'complex', with complex parameters. % % Returns % ------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the quasi-particle % state. @@ -313,20 +317,20 @@ % % Arguments % --------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the quasi-particle % state. % - % qp : :class:`InfQP` + % qp : :class:`.InfQP` % input quasi-particle state. % - % type : 'real' or 'complex' + % type : :class:`char`, 'real' or 'complex' % optionally specify if complex entries should be seen as 1 or 2 parameters. % Defaults to 'complex', with complex parameters. % % Returns % ------- - % qp : :class:`InfQP` + % qp : :class:`.InfQP` % output quasi-particle state, filled with the parameters. arguments diff --git a/src/mps/MpoTensor.m b/src/mps/MpoTensor.m index e3e278a..c90f8db 100644 --- a/src/mps/MpoTensor.m +++ b/src/mps/MpoTensor.m @@ -7,12 +7,16 @@ % .. code-block:: % % 4 - % ^ + % v % | - % 1 ->-- O -->- 3 + % 1 -<-- O --<- 3 % | - % ^ + % v % 2 + % + % Todo + % ---- + % Document. properties tensors = [] @@ -443,7 +447,7 @@ function disp(O) end function local_operators = decompose_local_operator(H, kwargs) - % convert a tensor into a product of local operators. + % Convert a tensor into a product of local operators. % % Usage % ----- @@ -451,14 +455,14 @@ function disp(O) % % Arguments % --------- - % H : :class:`AbstractTensor` + % H : :class:`.AbstractTensor` % tensor representing a local operator on N sites. % % Keyword Arguments % ----------------- - % 'Trunc' : cell + % 'Trunc' : :class:`cell` % optional truncation method for the decomposition. See also - % :meth:`Tensor.tsvd` + % :meth:`.Tensor.tsvd` arguments H kwargs.Trunc = {'TruncBelow', 1e-14} diff --git a/src/mps/MpsTensor.m b/src/mps/MpsTensor.m index 8385343..0c340ea 100644 --- a/src/mps/MpsTensor.m +++ b/src/mps/MpsTensor.m @@ -1,5 +1,20 @@ classdef (InferiorClasses = {?Tensor, ?SparseTensor}) MpsTensor < AbstractTensor - % Generic mps tensor objects that have a notion of virtual, physical and auxiliary legs. + % Generic MPS tensor objects that have a notion of virtual, physical and auxiliary legs. + % + % Properties + % ---------- + % var : :class:`.Tensor` or :class:`.SparseTensor` + % tensor data of the MPS tensor. + % + % plegs : :class:`int` + % number of physical legs. + % + % alegs : :class:`int` + % number of auxiliary legs. + % + % Todo + % ---- + % Document all methods. properties var @@ -109,7 +124,13 @@ end function tdst = insert_onespace(tsrc, varargin) - % insert a trivial space at position i. + % Insert a trivial space at position :code:`i`, corresponding to an additional + % auxiliary leg. + % + % See Also + % -------- + % :meth:`.Tensor.insert_onespace` + tdst = MpsTensor(insert_onespace(tsrc.var, varargin{:}), tsrc.alegs + 1); end end @@ -137,17 +158,17 @@ end function s = pspace(A) - % The physical space of an :class:`MpsTensor`. + % The physical space of an :class:`.MpsTensor`. s = space(A, 1 + (1:A.plegs)); end function s = leftvspace(A) - % The left virtual space of an :class:`MpsTensor`. + % The left virtual space of an :class:`.MpsTensor`. s = space(A.var(1), 1); end function s = rightvspace(A) - % The right virtual space of an :class:`MpsTensor`. + % The right virtual space of an :class:`.MpsTensor`. s = space(A.var(1), nspaces(A.var(1)) - A.alegs); end end @@ -326,16 +347,17 @@ % Usage % ----- % :code:`t = ctranspose(t)` + % % :code:`t = t'` % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.MpsTensor` % input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.MpsTensor` % adjoint tensor. for i = 1:numel(t) @@ -592,7 +614,7 @@ function disp(t) % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.MpsTensor` % input tensor. % % type : 'real' or 'complex' @@ -601,7 +623,7 @@ function disp(t) % % Returns % ------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the tensor. arguments @@ -617,19 +639,19 @@ function disp(t) % % Arguments % --------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the tensor. % - % t : :class:`Tensor` + % t : :class:`.MpsTensor` % input tensor. % - % type : 'real' or 'complex' + % type : :class:`char`, 'real' or 'complex' % optionally specify if complex entries should be seen as 1 or 2 parameters. % Defaults to 'complex', with complex parameters. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.MpsTensor` % output tensor, filled with the parameters. arguments @@ -654,14 +676,14 @@ function disp(t) % % Arguments % --------- - % H : :class:`AbstractTensor` - % tensor representing a local operator on N sites. + % psi : :class:`.AbstractTensor` + % tensor representing a local state on N sites. % % Keyword Arguments % ----------------- - % 'Trunc' : cell + % 'Trunc' : :class:`cell` % optional truncation method for the decomposition. See also - % :meth:`Tensor.tsvd` + % :meth:`.Tensor.tsvd` arguments psi kwargs.Trunc = {'TruncBelow', 1e-14} diff --git a/src/mps/PepsSandwich.m b/src/mps/PepsSandwich.m index 8ef343d..0db3ebd 100644 --- a/src/mps/PepsSandwich.m +++ b/src/mps/PepsSandwich.m @@ -1,6 +1,18 @@ classdef (InferiorClasses = {?Tensor, ?MpsTensor, ?SparseTensor}) PepsSandwich % Data structure representing a pair of PEPS tensors in an overlap, which behave as an % MPO tensor. + % + % Properties + % ---------- + % top : :class:`.PepsTensor` + % top-layer PEPS tensor, usually interpreted as the 'bra' in the overlap. + % + % bot : :class:`.PepsTensor` + % bottom-layer PEPS tensor, usually interpreted as the 'ket' in the overlap. + % + % Todo + % ---- + % Document. properties top PepsTensor diff --git a/src/mps/PepsTensor.m b/src/mps/PepsTensor.m index 3f49ca4..ad21039 100644 --- a/src/mps/PepsTensor.m +++ b/src/mps/PepsTensor.m @@ -1,8 +1,11 @@ classdef PepsTensor - % Generic PEPS tensor object that hos a notion of virtual and physical legs. - % This object represents the PEPS tensor at a single site as a rank (1, 4) tensor, - % where the physical index lies in the codomain and the virtual indices lie in the - % domain. + % Generic PEPS tensor object that has a notion of virtual and physical legs. + % + % This object represents the PEPS tensor at a single site as a rank (1, 4) tensor, + % where the physical index lies in the codomain and the virtual indices lie in the + % domain. + % + % .. code-block:: % % 5 1 % | / @@ -13,6 +16,15 @@ % ^ % | % 3 + % + % Properties + % ---------- + % var : :class:`.Tensor` + % PEPS tensor data. + % + % Todo + % ---- + % Document. properties var end diff --git a/src/mps/UniformMps.m b/src/mps/UniformMps.m index 3546490..0475a87 100644 --- a/src/mps/UniformMps.m +++ b/src/mps/UniformMps.m @@ -1,22 +1,28 @@ classdef UniformMps - % UniformMps - Implementation of infinite translation invariant MPS + % Implementation of infinite translation invariant MPS % % The center gauge is defined to have: - % :math:`AL_w * C_w = AC_w = C_{w-1} * AR_w` + % + % .. math:: + % AL_w \cdot C_w = AC_w = C_{w-1} \cdot AR_w % % Properties % ---------- - % AL : :class:`MpsTensor` + % AL : :class:`.MpsTensor` % left-gauged mps tensors. % - % AR : :class:`MpsTensor` + % AR : :class:`.MpsTensor` % right-gauged mps tensors. % - % C : :class:`Tensor` + % C : :class:`.Tensor` % center gauge transform. % - % AC : :class:`MpsTensor` + % AC : :class:`.MpsTensor` % center-gauged mps tensors. + % + % Todo + % ---- + % Document all methods. properties AL (1,:) cell @@ -37,18 +43,18 @@ % % Arguments % --------- - % A : :class:`cell` of :class:`MpsTensor` + % A : :class:`cell` of :class:`.MpsTensor` % set of tensors per site that define an MPS to be gauged. % - % AL, AR, AC : :class:`cell` of :class:`MpsTensor` + % AL, AR, AC : :class:`cell` of :class:`.MpsTensor` % set of gauged MpsTensors. % - % C : :class:`cell` of :class:`Tensor` + % C : :class:`cell` of :class:`.Tensor` % gauge tensor. % % Returns % ------- - % mps : :class:`UniformMps` + % mps : :class:`.UniformMps` % gauged uniform MPS. narginchk(0, 4); @@ -121,12 +127,12 @@ % fun : :class:`function_handle` % function to initialize the tensor. % - % Repeating Aruguments - % -------------------- - % pspaces : :class:`AbstractSpace` + % Repeating Arguments + % ------------------- + % pspaces : :class:`.AbstractSpace` % physical spaces for each site. % - % vspaces : :class:`AbstractSpace` + % vspaces : :class:`.AbstractSpace` % virtual spaces between each site. (entry `i` corresponds to left of site % `i`.) @@ -161,7 +167,7 @@ % % See Also % -------- - % :meth:`UniformMps.new` + % :meth:`.UniformMps.new` arguments (Repeating) pspaces @@ -176,12 +182,12 @@ %% Properties methods function p = period(mps) - % period over which the mps is translation invariant. + % Period over which the mps is translation invariant. p = length(mps(1).AL); end function d = depth(mps) - % amount of lines in a multi-line mps. + % Number of lines in a multi-line mps. d = size(mps, 1); end @@ -204,19 +210,19 @@ end function s = leftvspace(mps, w) - % return the virtual space to the left of site w. + % Return the virtual space to the left of site `w`. if nargin == 1 || isempty(w), w = 1:period(mps); end s = arrayfun(@leftvspace, mps.AL{w}); end function s = pspace(mps, w) - % return the physical space at site w. + % Return the physical space at site `w`. if nargin == 1 || isempty(w), w = 1:period(mps); end s = pspace(mps.AL{w}); end function s = rightvspace(mps, w) - % return the virtual space to the right of site w. + % Return the virtual space to the right of site `w`. if nargin == 1 || isempty(w), w = 1:period(mps); end s = arrayfun(@rightvspace, mps.AL{w}); end @@ -238,34 +244,35 @@ % % Arguments % --------- - % mps : :class:`UniformMps` + % mps : :class:`.UniformMps` % input mps, from which AL or AR is used as the state, and optionally C as an % initial guess for the gauge. % % Keyword Arguments % ----------------- - % Tol : numeric + % Tol : :class:`numeric` % tolerance for the algorithm. % - % MaxIter : integer - % maximum amount of iterations. + % MaxIter : :class:`integer` + % maximum number of iterations. % - % Method : char + % Method : :class:`char` % algorithm used for decomposition. Must be 'polar', 'qr' or 'qrpos'. % - % Verbosity : :class:`Verbosity` + % Verbosity : :class:`.Verbosity` % level of output. % - % DiagC : logical + % DiagC : :class:`logical` % flag to indicate if `C` needs to be diagonalized. % - % ComputeAC : logical + % ComputeAC : :class:`logical` % flag to indicate if `AC` needs to be computed. % - % Order : 'lr' or 'rl' + % Order : :class:`char`, 'lr' or 'rl' % order of gauge fixing: - % 'lr' uses AL as input tensors, first leftorth, then rightorth. - % 'rl' uses AR as input tensors, first rightorth, then leftorth. + % + % - 'lr' uses AL as input tensors, first :code:`leftorth`, then :class:`rightorth`. + % - 'rl' uses AR as input tensors, first :class:`rightorth`, then :code:`leftorth`. arguments mps @@ -364,7 +371,7 @@ end function mps = diagonalizeC(mps) - % gauge transform an mps such that C is diagonal. + % Gauge transform an mps such that C is diagonal. for i = 1:depth(mps) for w = 1:period(mps(i)) @@ -396,7 +403,7 @@ end function mps = normalize(mps) - % normalize an mps state. + % Normalize an mps state. mps.C = arrayfun(@normalize, mps.C); mps.AC = arrayfun(@normalize, mps.AC); @@ -422,25 +429,25 @@ % % Arguments % --------- - % mps1 : :class:`UniformMps` + % mps1 : :class:`.UniformMps` % input mps for top layer. % - % mps2 : :class:`UniformMps` + % mps2 : :class:`.UniformMps` % input mps for bottom layer, by default equal to the top. % - % sites : integer + % sites : :class:`int` % optionally slice the unit cell of the mps and only define the transfer % matrix for this slice. % % Keyword Arguments % ----------------- - % Type : char + % Type : :class:`char` % 'LL', 'LR', 'RL', 'RR' to determine if the top or bottom respectively are AL % or AR. % % Returns % ------- - % T : FiniteMpo + % T : :class:`.FiniteMpo` % transfer matrix of an mps, acting to the left. arguments @@ -475,16 +482,16 @@ % % Arguments % --------- - % mps : :class:`UniformMps` + % mps : :class:`.UniformMps` % input state. % - % type : char + % type : :class:`char` % specification of the type of transfer matrix: - % general format: sprintf(%c_%c%c, side, top, bot) where side is 'l' or 'r' to + % general format: :code:`sprintf(%c_%c%c, side, top, bot)` where side is 'l' or 'r' to % determine which fixedpoint, and top and bot are 'L' or 'R' to specify % whether to use AL or AR in the transfer matrix. % - % w : integer + % w : :class:`int` % position within the mps unitcell of the fixed point. arguments @@ -533,30 +540,31 @@ % % Arguments % --------- - % mps1 : :class:`UniformMps` + % mps1 : :class:`.UniformMps` % input mps for top layer. % - % mps2 : :class:`UniformMps` + % mps2 : :class:`.UniformMps` % input mps for bottom layer. Default value equal to `mps1`. % - % howmany : integer + % howmany : :class:`int` % number of eigenvectors and eigenvalues to compute. % - % which : 'char' + % which : :class:`char` % type of eigenvectors to target. % % Keyword Arguments % ----------------- % eigopts - % see keyword arguments for :meth:`eigs`. + % see keyword arguments for :func:`.eigsolve`. % - % Verbosity : integer + % Verbosity : :class:`int` % detail level for output. % - % Type : 'char' - % type of transfer matrix to construct. + % Type : :class:`char` + % type of transfer matrix to construct, see + % :meth:`.UniformMps.transfermatrix`. % - % Charge : :class:`AbstractCharge` + % Charge : :class:`.AbstractCharge` % charge of eigenvectors to target. arguments @@ -597,6 +605,8 @@ end function f = fidelity(mps1, mps2, kwargs) + % Compute the fidelity between two uniform MPSs. + arguments mps1 mps2 @@ -612,6 +622,8 @@ end function E = expectation_value(mps1, O, mps2) + % Compute the expectation value of an operator. + arguments mps1 O @@ -646,6 +658,8 @@ end function E = local_expectation_value(mps, O, offset) + % Compute the expectation value of a local operator. + arguments mps O @@ -667,6 +681,13 @@ end function [svals, charges] = schmidt_values(mps, w) + % Compute the Schmidt values and corresponding charges for an entanglement cut + % to the right of site :code:`w`. + % + % Usage + % ----- + % :code:`[svals, charges] = schmidt_values(mps, w)` + arguments mps w = 1 @@ -677,6 +698,8 @@ end function plot_entanglementspectrum(mps, d, w, ax, kwargs) + % Plot the entanglement spectrum of a uniform MPS. + arguments mps d = 1:depth(mps) @@ -754,18 +777,18 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) % % Arguments % --------- - % mps : :class:`UniformMps` + % mps : :class:`.UniformMps` % input mps. % - % charge : :class:`AbstractCharge` + % charge : :class:`.AbstractCharge` % charge sector for correlation length to target. % % Returns % ------- - % xi : numeric + % xi : :class:`numeric` % correlation length in the given charge sector. % - % theta : numeric + % theta : :class:`numeric` % angle of the corresponding oscillation period. arguments @@ -799,32 +822,32 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) % % Arguments % --------- - % mps : :class:`UniformMps` + % mps : :class:`.UniformMps` % input mps. % - % charge : :class:`AbstractCharge` + % charge : :class:`.AbstractCharge` % charge sector for correlation length to target. % % Keyword Arguments % ----------------- - % HowMany : int + % HowMany : :class:`int` % amount of transfer matrix eigenvalues to compute. % - % Angle : numeric + % Angle : :class:`numeric` % angle in radians around which the gap should be computed. % - % AngleTol : numeric + % AngleTol : :class:`numeric` % tolerance in radians for angles to be considered equal. % % Returns % ------- - % epsilon : numeric + % epsilon : :class:`numeric` % inverse correlation length in the given charge sector. % - % delta : numeric + % delta : :class:`numeric` % refinement parameter. % - % spectrum : numeric + % spectrum : :class:`numeric` % computed partial transfer matrix spectrum. arguments mps @@ -859,6 +882,8 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) end function S = entanglement_entropy(mps, w) + % Compute the entanglement entropy of a uniform MPS for a cut to the right of + % site :code:`w` arguments mps w = 1 @@ -873,7 +898,9 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) end function S = renyi_entropy(mps, n, w) - arguments + % Compute the :code:`n`-th Renyi entropy of a uniform MPS for a cut to the right + % of site :code:`w` + arguments mps n w = 1 @@ -889,6 +916,8 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) end function out = truncate(mps, trunc) + % Truncate a uniform MPS according to the options specified in :code:`trunc` + % (see :meth:`.Tensor.tsvd` for details on the truncation options). arguments mps trunc.TruncDim @@ -911,32 +940,32 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) end end - S = EntanglementEntropy(mps, loc); - S = RenyiEntropy(mps,n, loc); - E = ExpectationValue(mps, W, GL, GR) - rho = LeftFixedPoint(mps1, mps2, w, choice) - rho = RightFixedPoint(mps1, mps2, w, choice) - sf=StaticStructureFactor(mps,S,k) - - out = Block(mps, opts) - out = Split(mps, varargin) - %[out, lambda] = Truncate(mps, control, opts) - - [f, rho] = Fidelity(mps1, mps2, tol) - - mps = Conj(mps) - - mps = mtimes(mps, lambda) - - mps = ShiftUnitCell(mps,dd,dw) - out = Rotate180(mps) - out = Transpose(mps) - - mps = SendToGpu(mps) - mps = GetFromGpu(mps) - - [mps, xi] = Retract(mps, eta, alpha) - n = Inner(x, eta, xi) +% S = EntanglementEntropy(mps, loc); +% S = RenyiEntropy(mps,n, loc); +% E = ExpectationValue(mps, W, GL, GR) +% rho = LeftFixedPoint(mps1, mps2, w, choice) +% rho = RightFixedPoint(mps1, mps2, w, choice) +% sf=StaticStructureFactor(mps,S,k) +% +% out = Block(mps, opts) +% out = Split(mps, varargin) +% %[out, lambda] = Truncate(mps, control, opts) +% +% [f, rho] = Fidelity(mps1, mps2, tol) +% +% mps = Conj(mps) +% +% mps = mtimes(mps, lambda) +% +% mps = ShiftUnitCell(mps,dd,dw) +% out = Rotate180(mps) +% out = Transpose(mps) +% +% mps = SendToGpu(mps) +% mps = GetFromGpu(mps) +% +% [mps, xi] = Retract(mps, eta, alpha) +% n = Inner(x, eta, xi) end @@ -944,6 +973,11 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) %% Subroutines methods (Access = protected) function [AL, CL, lambda, eta] = uniform_leftorth(mps, CL, kwargs) + % Bring a uniform MPS into left canonical form. + % + % Usage + % ----- + % :code:`[AL, CL, lambda, eta] = uniform_leftorth(mps, CL, kwargs)` arguments mps CL = {} @@ -1047,6 +1081,11 @@ function plot_entanglementspectrum(mps, d, w, ax, kwargs) end function [AR, CR, lambda, eta] = uniform_rightorth(mps, CR, kwargs) + % Bring a uniform MPS into right canonical form. + % + % Usage + % ----- + % :code:`[AR, CR, lambda, eta] = uniform_rightorth(mps, CR, kwargs)` arguments mps CR = mps.C diff --git a/src/sparse/SparseTensor.m b/src/sparse/SparseTensor.m index f51f20f..b9b41b4 100644 --- a/src/sparse/SparseTensor.m +++ b/src/sparse/SparseTensor.m @@ -1,5 +1,9 @@ classdef (InferiorClasses = {?Tensor}) SparseTensor < AbstractTensor % Class for multi-dimensional sparse objects. + % + % Todo + % ---- + % Document properties, behavior and methods. %#ok<*PROPLC> diff --git a/src/tensors/Tensor.m b/src/tensors/Tensor.m index 972df75..3ad91bf 100644 --- a/src/tensors/Tensor.m +++ b/src/tensors/Tensor.m @@ -511,6 +511,18 @@ function tdst = insert_onespace(tsrc, i, dual) % Insert a trivial space at position :code:`i`. + % + % Arguments + % --------- + % tsrc : :class:`.Tensor` + % input tensor. + % + % i : :class:`int` + % position at which to insert trivial space, defaults to the last index. + % + % dual : :class:`logical` + % indicate whether or not to dualize the trivial space, defaults to + % :code:`false`. arguments tsrc i = nspaces(tsrc) + 1 @@ -1564,10 +1576,10 @@ % Returns % ------- % Q : :class:`.Tensor` - % Orthonormal basis tensor + % orthonormal basis tensor. % % R : :class:`.Tensor` - % Remainder tensor, depends on selected algorithm. + % remainder tensor, depends on selected algorithm. arguments t diff --git a/src/utility/Options.m b/src/utility/Options.m index 753dc5c..39c12b6 100644 --- a/src/utility/Options.m +++ b/src/utility/Options.m @@ -1,9 +1,15 @@ classdef Options % Various package settings. - methods (Static) function bool = CacheEnabled(bool) + % Enable cache. + % + % Usage + % ----- + % :code:`bool = Options.CacheEnabled(bool)` sets the cache enabling to :code:`bool`. + % + % :code:`bool = Options.CacheEnabled(bool)` returns the current cache enabling. persistent isenabled if nargin > 0 isenabled = bool; @@ -15,6 +21,13 @@ end function bool = Debug(bool) + % Enable cache. + % + % Usage + % ----- + % :code:`bool = Options.Debug(bool)` sets the debug mode to :code:`bool`. + % + % :code:`bool = Options.Debug(bool)` returns the current debug mode. persistent dodebug if nargin > 0 dodebug = bool; diff --git a/src/utility/Verbosity.m b/src/utility/Verbosity.m index fb0d412..35e972a 100644 --- a/src/utility/Verbosity.m +++ b/src/utility/Verbosity.m @@ -1,5 +1,14 @@ classdef Verbosity < uint8 % Verbosity level enumeration class. + % + % Levels: + % + % - off (0): No information + % - warn (1): Information on failure + % - conv (2): Convergence information + % - iter (3): Information about each iteration + % - detail (4): Detailed information about each iteration + % - diagnostics (255): All possible information enumeration off (0) % No information diff --git a/src/utility/between.m b/src/utility/between.m index 944f40b..9425644 100644 --- a/src/utility/between.m +++ b/src/utility/between.m @@ -1,4 +1,5 @@ function x = between(x1, x, x2) +% Restrict :code:`x` to lie between :code:`x1` and :code:`x2` assert(x1 <= x2, 'range', 'x1 should be smaller than or equal to x2'); if x < x1 diff --git a/src/utility/colors.m b/src/utility/colors.m index 37d5628..446de07 100644 --- a/src/utility/colors.m +++ b/src/utility/colors.m @@ -1,4 +1,5 @@ function y = colors(i) +% Periodically cycle through standard Matlab colors. y=[0 0.4470 0.7410 0.8500 0.3250 0.0980 diff --git a/src/utility/dim2str.m b/src/utility/dim2str.m index a403bc7..4d1b693 100644 --- a/src/utility/dim2str.m +++ b/src/utility/dim2str.m @@ -1,4 +1,5 @@ function s = dim2str(sz) +% Convert size array to string output. s = regexprep(mat2str(sz), {'\[', '\]', '\s+'}, {'', '', 'x'}); diff --git a/src/utility/diracdelta.m b/src/utility/diracdelta.m index 2ed8d80..93f40b2 100644 --- a/src/utility/diracdelta.m +++ b/src/utility/diracdelta.m @@ -1,4 +1,5 @@ function d = diracdelta(sz) +% Construct delta tensor of given size. Note that all dimensions must have the same length. assert(all(sz == sz(1))) d = zeros(sz); diff --git a/src/utility/indices/contractinds.m b/src/utility/indices/contractinds.m index 14ab24e..726e387 100644 --- a/src/utility/indices/contractinds.m +++ b/src/utility/indices/contractinds.m @@ -2,7 +2,7 @@ % Find the contracted dimensions. % % :code:`[dimA, dimB] = contractinds(ia, ib)` -% locates the repeated indices. +% locates the repeated indices in two vectors of integers. ind = find(ia(:) == ib).' - 1; dimA = mod(ind, length(ia)) + 1; diff --git a/src/utility/indices/mod1.m b/src/utility/indices/mod1.m index 3c0207a..2b86986 100644 --- a/src/utility/indices/mod1.m +++ b/src/utility/indices/mod1.m @@ -1,17 +1,17 @@ function m = mod1(x, y) -% Modulus after division, counting from 1:y. +% Modulus after division, counting from :code:`1:y`. % % Arguments % --------- -% x : int +% x : :class:`int` % numerator. % -% y : int +% y : :class:`int` % divisor. % % Returns % ------- -% m : int +% m : :class:`int` % remainder after division, where a value of 0 is replaced with y. m = mod(x-1, y) + 1; diff --git a/src/utility/indices/next.m b/src/utility/indices/next.m index 60bbaba..cfa0afb 100644 --- a/src/utility/indices/next.m +++ b/src/utility/indices/next.m @@ -4,11 +4,11 @@ % Usage % ----- % :code:`j = next(i, total)` -% gives the :math:`i + 1`'th index, but loops back to 1 when :math:`j > \text{total}`. +% gives the :math:`i + 1`'th index, but loops back to 1 when :math:`j > \text{total}`. % % See Also % -------- -% :func:`prev` +% :func:`.prev` j = mod(i, total) + 1; diff --git a/src/utility/indices/prev.m b/src/utility/indices/prev.m index ed2ef71..3489dd7 100644 --- a/src/utility/indices/prev.m +++ b/src/utility/indices/prev.m @@ -4,11 +4,11 @@ % Usage % ----- % :code:`j = prev(i, total)` -% gives the :math:`i - 1`'th index, but loops back to total when :math:`j < 1`. +% gives the :math:`i - 1`'th index, but loops back to total when :math:`j < 1`. % % See Also % -------- -% :func:`next` +% :func:`.next` j = mod(i - 2, total) + 1; diff --git a/src/utility/indices/rankrange.m b/src/utility/indices/rankrange.m index 8751470..153bc01 100644 --- a/src/utility/indices/rankrange.m +++ b/src/utility/indices/rankrange.m @@ -1,6 +1,5 @@ function r = rankrange(rank) -%RANKRANGE Summary of this function goes here -% Detailed explanation goes here +% Convert tensor rank into a contiguous range of dimensions. r = [1:rank(1) rank(1) + (rank(2):-1:1)]; diff --git a/src/utility/indices/traceinds.m b/src/utility/indices/traceinds.m index 8340e66..6d75ffe 100644 --- a/src/utility/indices/traceinds.m +++ b/src/utility/indices/traceinds.m @@ -1,4 +1,8 @@ function [dimA1, dimA2] = traceinds(ia) +% Find the traced dimensions. +% +% :code:`[dimA1, dimA2] = traceinds(ia)` +% locates the repeated indices in a vectors of integers. ind = find(ia(:) == ia & ~tril(true(length(ia)))).' - 1; dimA1 = mod(ind, length(ia)) + 1; diff --git a/src/utility/indices/treeindsequence.m b/src/utility/indices/treeindsequence.m index 791e91a..d570059 100644 --- a/src/utility/indices/treeindsequence.m +++ b/src/utility/indices/treeindsequence.m @@ -7,12 +7,12 @@ % % Arguments % --------- -% n : int +% n : :class:`int` % number of external edges % % Returns % ------- -% t : int +% t : :class:`int` % total number of edges % % Example diff --git a/src/utility/indices/unique1.m b/src/utility/indices/unique1.m index d1e6b03..f5cb5d8 100644 --- a/src/utility/indices/unique1.m +++ b/src/utility/indices/unique1.m @@ -4,7 +4,7 @@ % Usage % ----- % :code:`inds = unique1(inds)` -% deletes all elements that appear more than once. +% deletes all elements that appear more than once. inds = inds(sum(inds(:) == inds) == 1); diff --git a/src/utility/linalg/contract.m b/src/utility/linalg/contract.m index 7a3c1b3..8da895a 100644 --- a/src/utility/linalg/contract.m +++ b/src/utility/linalg/contract.m @@ -11,23 +11,23 @@ % % Repeating Arguments % ------------------- -% tensors : :class:`Tensor` +% tensors : :class:`.Tensor` % list of tensors that constitute the vertices of the network. % -% indices : int -% list of indices that define the links and contraction order, using ncon-like syntax. +% indices : (1, :) :class:`int` +% list of indices that define the links and contraction order, using `ncon-like syntax `_. % % Keyword Arguments % ----------------- -% Conj : (1, :) logical +% Conj : (1, :) :class:`logical` % optional list to flag that tensors should be conjugated. % -% Rank : (1, 2) int +% Rank : (1, 2) :class:`int` % optionally specify the rank of the resulting tensor. % % Returns % ------- -% C : :class:`Tensor` or numeric +% C : :class:`.Tensor` or :class:`numeric` % result of the tensor network contraction. % TODO contraction order checker, order specifier. diff --git a/src/utility/linalg/eigsolve.m b/src/utility/linalg/eigsolve.m index 860486c..9c1ae78 100644 --- a/src/utility/linalg/eigsolve.m +++ b/src/utility/linalg/eigsolve.m @@ -4,28 +4,29 @@ % Usage % ----- % :code:`[V, D, flag] = eigsolve(A, v, howmany, sigma, kwargs)` +% % :code:`D = eigsolve(A, v, ...)` % % Arguments % --------- -% A : matrix or function_handle +% A : :class:`matrix` or :class:`function_handle` % A square matrix. % A function handle which implements one of the following, depending on sigma: % -% - A \ x, if `sigma` is 0 or 'smallestabs' -% - (A - sigma * I) \ x, if sigma is a nonzero scalar -% - A * x, for all other cases +% - :code:`A \ x`, if `sigma` is 0 or 'smallestabs' +% - :code:`(A - sigma * I) \ x`, if sigma is a nonzero scalar +% - :code:`A * x`, for all other cases % -% v : vector -% initial guess for the eigenvector. If A is a :class:`Tensor`, this defaults -% to a random complex :class:`Tensor`, for function handles this is a required +% v : :class:`vector` +% initial guess for the eigenvector. If A is a :class:`.Tensor`, this defaults +% to a random complex :class:`.Tensor`, for function handles this is a required % argument. % -% howmany : int +% howmany : :class:`int` % amount of eigenvalues and eigenvectors that should be computed. By default % this is 1, and this should not be larger than the total dimension of A. % -% sigma : `char` or numeric +% sigma : :class:`char` or :class:`numeric` % selector for the eigenvalues, should be either one of the following: % % - 'largestabs', 'lm': default, eigenvalues of largest magnitude @@ -34,52 +35,43 @@ % - 'smallestabs', 'sm': default, eigenvalues of smallest magnitude % - 'smallestreal', 'sr': eigenvalues with smallest real part % - 'smallestimag', 'si': eigenvalues with smallest imaginary part. -% - 'bothendsreal', 'be': both ends, with howmany/2 values with largest and -% smallest real part respectively. -% - 'bothendsimag', 'li': both ends, with howmany/2 values with largest and -% smallest imaginary part respectively. % - numeric : eigenvalues closest to sigma. % % Keyword Arguments % ----------------- -% Tol : numeric +% Tol : :class:`double` % tolerance of the algorithm. % -% Algorithm : char +% Algorithm : :class:`char` % choice of eigensolver algorithm. Currently there is a choice between the use % of Matlab's buitin `eigs` specified by the identifiers 'eigs' or % 'KrylovSchur', or the use of a custom Arnolid algorithm specified by % the identifier 'Arnoldi'. % -% MaxIter : int +% MaxIter : :class:`int` % maximum number of iterations, 100 by default. % -% KrylovDim : int +% KrylovDim : :class:`int` % number of vectors kept in the Krylov subspace. % -% IsSymmetric : logical +% IsSymmetric : :class:`logical` % flag to speed up the algorithm if the operator is symmetric, false by % default. % -% Verbosity : int +% Verbosity : :class:`.Verbosity` % Level of output information, by default nothing is printed if `flag` is -% returned, otherwise only warnings are given. -% -% - 0 : no information -% - 1 : information at failure -% - 2 : information at convergence -% - 3 : information at every iteration +% returned, otherwise only warnings are given, defaults to :code:`Verbosity.warn`. % % Returns % ------- -% V : (1, howmany) array +% V : (1, howmany) :class:`vector` % vector of eigenvectors. % -% D : numeric +% D : :class:`numeric` % vector of eigenvalues if only a single output argument is asked, diagonal % matrix of eigenvalues otherwise. % -% flag : int +% flag : :class:`int` % if flag = 0 then all eigenvalues are converged, otherwise not. arguments diff --git a/src/utility/linalg/isapprox.m b/src/utility/linalg/isapprox.m index f131a6c..f2de936 100644 --- a/src/utility/linalg/isapprox.m +++ b/src/utility/linalg/isapprox.m @@ -1,4 +1,23 @@ function bool = isapprox(A, B, tol) +% Verify whether two arrays are approximately equal, based on their Euclidean distance. +% +% Arguments +% --------- +% A, B : :class:`numeric` +% input arrays of the same size. +% +% Keyword Arguments +% ----------------- +% AbsTol : :class:`double` +% absolute tolerance. +% +% RelTol : :code:`double` +% relative tolerance. +% +% Returns +% ------- +% bool : :code:`logical` +% true if :code:`A` and :code:`B` are approximately equal. arguments A diff --git a/src/utility/linalg/isisometry.m b/src/utility/linalg/isisometry.m index a4fc99e..f8026a0 100644 --- a/src/utility/linalg/isisometry.m +++ b/src/utility/linalg/isisometry.m @@ -3,24 +3,24 @@ % % Arguments % --------- -% A : numeric +% A : :class:`numeric` % input matrix. % -% side : 'left', 'right' or 'both' -% check if A' * A == I, A * A' == I, or both by default. +% side : :class:`char`, 'left', 'right' or 'both' +% check if :code:`A' * A == I`, :code:`A * A' == I`, or both by default. % % Keyword Arguments % ----------------- -% AbsTol : double +% AbsTol : :class:`double` % absolute tolerance % -% RelTol : double +% RelTol : :code:`double` % relative tolerance % % Returns % ------- -% bool : logical -% true if A is an isometry. +% bool : :code:`logical` +% true if :code:`A` is an isometry. arguments A diff --git a/src/utility/linalg/leftnull.m b/src/utility/linalg/leftnull.m index c547045..483dffa 100644 --- a/src/utility/linalg/leftnull.m +++ b/src/utility/linalg/leftnull.m @@ -1,20 +1,21 @@ function N = leftnull(A, alg, atol) -% Compute the left nullspace of a matrix, such that N' * A = 0. +% Compute the left nullspace of a matrix, such that :code:`N' * A == 0`. % % Arguments % --------- -% A : numeric +% A : :class:`numeric` % input matrix. % -% alg : 'qr' or 'svd' +% alg : :class:`char`, 'qr' or 'svd' % choice of algorithm, default 'svd'. % -% atol : double -% absolute tolerance for the null space, defaults to max(size(A)) * eps(max(svd(A))). +% atol : :class:`double` +% absolute tolerance for the null space, defaults to +% :code:`max(size(A)) * eps(max(svd(A)))`. % % Returns % ------- -% N : numeric +% N : :class:`numeric` % orthonormal basis for the orthogonal complement of the support of the row space of A. arguments diff --git a/src/utility/linalg/leftorth.m b/src/utility/linalg/leftorth.m index ff8fd48..82b00fe 100644 --- a/src/utility/linalg/leftorth.m +++ b/src/utility/linalg/leftorth.m @@ -1,10 +1,36 @@ function [Q, R] = leftorth(A, alg) - - +% Factorize a matrix into an orthonormal basis `Q` and remainder `R`, such that +% :code:`A = Q * R`. +% +% Usage +% ----- +% :code:`[Q, R] = leftorth(A, alg)` +% +% Arguments +% --------- +% A : :class:`numeric` +% input matrix to factorize. +% +% alg : :class:`char` or :class:`string` +% selection of algorithms for the decomposition: +% +% - 'qr' produces an upper triangular remainder R +% - 'qrpos' corrects the diagonal elements of R to be positive. +% - 'ql' produces a lower triangular remainder R +% - 'qlpos' corrects the diagonal elements of R to be positive. +% - 'polar' produces a Hermitian and positive semidefinite R. +% - 'svd' uses a singular value decomposition. +% +% Returns +% ------- +% Q : :class:`numeric` +% orthonormal basis matrix +% +% R : :class:`numeric` +% remainder matrix, depends on selected algorithm. % TODO have a look at https://github.com/iwoodsawyer/factor - switch alg case 'qr' [Q, R] = qr(A, 0); diff --git a/src/utility/linalg/rightnull.m b/src/utility/linalg/rightnull.m index f891242..0ad7412 100644 --- a/src/utility/linalg/rightnull.m +++ b/src/utility/linalg/rightnull.m @@ -1,21 +1,23 @@ function N = rightnull(A, alg, atol) -% Compute the right nullspace of a matrix, such that A * N' = 0. +% Compute the right nullspace of a matrix, such that :code:`A * N' == 0`. % % Arguments % --------- -% A : numeric +% A : :class:`numeric` % input matrix. % -% alg : 'lq' or 'svd' +% alg : :class:`char`, 'lq' or 'svd' % choice of algorithm, default 'svd'. % -% atol : double -% absolute tolerance for the null space, defaults to max(size(A)) * eps(max(svd(A))). +% atol : :class:`double` +% absolute tolerance for the null space, defaults to +% :code:`max(size(A)) * eps(max(svd(A)))`. % % Returns % ------- -% N : numeric -% orthonormal basis for the orthogonal complement of the support of the column space of A. +% N : :class:`numeric` +% orthonormal basis for the orthogonal complement of the support of the column space of +% :code:`A`. arguments A diff --git a/src/utility/linalg/rightorth.m b/src/utility/linalg/rightorth.m index ca2ac50..3e54e2d 100644 --- a/src/utility/linalg/rightorth.m +++ b/src/utility/linalg/rightorth.m @@ -1,7 +1,33 @@ function [R, Q] = rightorth(A, alg) - - - +% Factorize a matrix into an orthonormal basis `Q` and remainder `L`, such that +% :code:`A = L * Q`. +% +% Usage +% ----- +% :code:`[R, Q] = rightorth(A, alg)` +% +% Arguments +% --------- +% A : :class:`numeric` +% input matrix to factorize. +% +% alg : :class:`char` or :class:`string` +% selection of algorithms for the decomposition: +% +% - 'rq' produces an upper triangular remainder R +% - 'rqpos' corrects the diagonal elements of R to be positive. +% - 'lq' produces a lower triangular remainder R +% - 'lqpos' corrects the diagonal elements of R to be positive. +% - 'polar' produces a Hermitian and positive semidefinite R. +% - 'svd' uses a singular value decomposition. +% +% Returns +% ------- +% R : :class:`numeric` +% remainder matrix, depends on selected algorithm. +% +% Q : :class:`numeric` +% orthonormal basis matrix. % TODO have a look at https://github.com/iwoodsawyer/factor diff --git a/src/utility/linalg/tensorprod.m b/src/utility/linalg/tensorprod.m index f76dde3..16f0c3b 100644 --- a/src/utility/linalg/tensorprod.m +++ b/src/utility/linalg/tensorprod.m @@ -4,18 +4,22 @@ % Usage % ----- % :code:`C = tensorprod(A, B, dimA, dimB)` -% returns the tensor product of tensors A and B. The arguments dimA and dimB are -% vectors that specify which dimensions to contract in A and B. The size of the -% output tensor is the size of the uncontracted dimensions of A followed by the size -% of the uncontracted dimensions of B. +% +% returns the tensor product of tensors :code:`A` and :code:`B`. The arguments :code:`dimA` +% and :code:`dimB` are vectors that specify which dimensions to contract in :code:`A` and +% :code:`B`. The size of the +% output tensor is the size of the uncontracted dimensions of :code:`A` followed by the size +% of the uncontracted dimensions of :code:`B`. % % :code:`C = tensorprod(A, B)` -% returns the outer product of tensors A and B. This is equivalent to the previous -% syntax with dimA = dimB = []. +% +% returns the outer product of tensors :code:`A` and :code:`B`. This is equivalent to the +% previous syntax with :code:`dimA = dimB = []`. % % :code:`C = tensorprod(_, NumDimensionsA=ndimsA)` -% optionally specifies the number of dimensions in tensor A in addition to combat the -% removal of trailing singleton dimensions. +% +% optionally specifies the number of dimensions in tensor :code:`A` in addition to combat the +% removal of trailing singleton dimensions. arguments A diff --git a/src/utility/linalg/tensortrace.m b/src/utility/linalg/tensortrace.m index d71cbd9..5fe2727 100644 --- a/src/utility/linalg/tensortrace.m +++ b/src/utility/linalg/tensortrace.m @@ -4,11 +4,13 @@ % Usage % ----- % -% :code:`[C, ic] = tensortrace(A, ia)` -% traces over the indices that appear twice in ia. +% :code:`[C, ic] = tensortrace(A, i1)` +% +% traces over the indices that appear twice in :code:`i1`. % -% :code:`[C, ic] = tensortrace(A, ia, ic)` -% optionally specifies the output indices' order. +% :code:`[C, ic] = tensortrace(A, i1, i2)` +% +% optionally specifies the output indices' order. if isempty(i1) && isempty(i2), C = A; return; end assert(length(i1) == length(i2), 'invalid indices'); diff --git a/src/utility/memsize.m b/src/utility/memsize.m index c266585..ebe1e73 100644 --- a/src/utility/memsize.m +++ b/src/utility/memsize.m @@ -1,4 +1,9 @@ function [bytes, unit] = memsize(in, unit) +% Check memory size of object in prefered unit ('GB', 'MB', 'KB' or 'B'). +% +% Usage +% ----- +% :code:`[bytes, unit] = memsize(in, unit)` if isa(in, 'containers.Map') warning('off', 'MATLAB:structOnObject'); diff --git a/src/utility/mod1.m b/src/utility/mod1.m deleted file mode 100644 index 1e9d522..0000000 --- a/src/utility/mod1.m +++ /dev/null @@ -1,9 +0,0 @@ -function i = mod1(i, N) - - -i = mod(i, N); -i(i == 0) = N; - - -end - diff --git a/src/utility/permutations/invperm.m b/src/utility/permutations/invperm.m index 35a4e49..9922649 100644 --- a/src/utility/permutations/invperm.m +++ b/src/utility/permutations/invperm.m @@ -1,9 +1,11 @@ function invp = invperm(p) -% Compute the inverse permutation. +% Compute the inverse of an integer permutation. +% % Usage % ----- % :code:`invp = invperm(p)` -% computes the permutation that satisfies :code:`invp(p) = 1:length(p)`. +% +% computes the permutation that satisfies :code:`invp(p) = 1:length(p)`. invp(p) = 1:length(p); diff --git a/src/utility/permutations/isperm.m b/src/utility/permutations/isperm.m index 4a1a635..5f6617a 100644 --- a/src/utility/permutations/isperm.m +++ b/src/utility/permutations/isperm.m @@ -1,6 +1,9 @@ function bool = isperm(p) -% isperm - Check if a vector is a permutation. -% bool = isperm(p) +% Check if a vector is a permutation. +% +% Usage +% ----- +% :code:`bool = isperm(p)` bool = all(sort(p) == 1:length(p)); diff --git a/src/utility/permutations/perm2swap.m b/src/utility/permutations/perm2swap.m index 4cd3075..b873c59 100644 --- a/src/utility/permutations/perm2swap.m +++ b/src/utility/permutations/perm2swap.m @@ -3,14 +3,14 @@ % % Arguments % --------- -% p : int +% p : :class:`int` % permutation vector. % % Returns % ------- -% s : int -% list of swaps that compose into the permutation vector, where `i` indicates a swap -% between indices `i` and `i+1`. +% s : :class:`int` +% list of swaps that compose into the permutation vector, where :code:`i` indicates a swap +% between indices :code:`i` and :code:`i+1`. N = length(p); s = []; diff --git a/src/utility/randc.m b/src/utility/randc.m index cb0bbdd..d44c00d 100644 --- a/src/utility/randc.m +++ b/src/utility/randc.m @@ -14,18 +14,18 @@ % % Arguments % --------- -% m, n, p, ... : int +% m, n, p, ... : :class:`int` % integers defining the size of the output array. % % classname : :class:`char` -% datatype of the array, default :class:`double`. +% datatype of the array, default :code:`'double'`. % -% Y : numeric +% Y : :class:`numeric` % create an array of the same class as Y. % % Returns % ------- -% R : numeric +% R : :class:`numeric` % complex pseudorandom values, real and imaginary part distributed from the uniform % distribution. diff --git a/src/utility/randnc.m b/src/utility/randnc.m index 5d884bc..c69d4f0 100644 --- a/src/utility/randnc.m +++ b/src/utility/randnc.m @@ -14,18 +14,18 @@ % % Arguments % --------- -% m, n, p, ... : int +% m, n, p, ... : :class:`int` % integers defining the size of the output array. % % classname : :class:`char` -% datatype of the array, default :class:`double`. +% datatype of the array, default :code:`'double'`. % -% Y : numeric +% Y : :class:`numeric` % create an array of the same class as Y. % % Returns % ------- -% R : numeric +% R : :class:`numeric` % complex pseudorandom values, real and imaginary part distributed from the normal % distribution. diff --git a/src/utility/simulsort.m b/src/utility/simulsort.m index 09b6e89..e99c8b7 100644 --- a/src/utility/simulsort.m +++ b/src/utility/simulsort.m @@ -19,18 +19,18 @@ % % Keyword Arguments % ----------------- -% Dimension : int +% Dimension : :class:`int` % determine the dimension along which to sort. This behaves similarly to SORT, by default: % - for vectors, sorts the elements % - for matrices, sorts each column % - for N-D arrays, sorts along the first non-singleton dimension. % -% Direction : 'ascend' or 'descend' +% Direction : :class:`char`, 'ascend' or 'descend' % specify the sorting direction, defaults to 'ascend'. % % Returns % ------- -% I : int +% I : :class:`int` % permutation vector that brings the input arrays into sorted order. % % array1, array2, ... diff --git a/src/utility/simulsortrows.m b/src/utility/simulsortrows.m index 0be7897..150e89e 100644 --- a/src/utility/simulsortrows.m +++ b/src/utility/simulsortrows.m @@ -1,33 +1,34 @@ function [I, varargout] = simulsortrows(arrays, kwargs) % Simultaneous sorting of several input arrays by row. -% Sorts the rows such that equal rows of array{i} appear sorted by the rows of array{i+1}. +% +% Sorts the rows such that equal rows of array{i} appear sorted by the rows of array{i+1}. % % This is achieved by sorting rows from end to front, making use of the fact that SORTROWS % is stable and thus will not mess up the order of later rows when earlier rows are equal. % % Usage % ----- -% [I, array1, array2, ...] = simulsortrows(array1, array2, ..., kwargs) +% :code:`[I, array1, array2, ...] = simulsortrows(array1, array2, ..., kwargs)` % -% Arguments -% --------- +% Repeating arguments +% ------------------- % array1, array2, ... % arrays of equal size that need to be sorted. These can be of any type that supports % SORTROWS. % % Keyword Arguments % ----------------- -% Col : int +% Col : :class:`int` % vector of indices that specifies the columns used for sorting. % -% Direction : 'ascend' or 'descend' +% Direction : :class:`char`, 'ascend' or 'descend' % specify the sorting direction. You can also specify a different direction for each % column by using a cell array of 'ascend' and 'descend' of the same size as Col, such % that corresponding elements are sorted ascending or descending. % % Returns % ------- -% I : int +% I : :class:`int` % permutation vector that brings the input arrays into rowsorted order. % % array1, array2, ... diff --git a/src/utility/simulunique.m b/src/utility/simulunique.m index 27a2e6a..adf65f6 100644 --- a/src/utility/simulunique.m +++ b/src/utility/simulunique.m @@ -1,5 +1,5 @@ function varargout = simulunique(varargin) -%SIMULUNIQUE Set unique over multiple arrays. +% Set unique over multiple arrays. nlhs = max(1, nargout); diff --git a/src/utility/sparse/SparseArray.m b/src/utility/sparse/SparseArray.m index e6de5a8..0428552 100644 --- a/src/utility/sparse/SparseArray.m +++ b/src/utility/sparse/SparseArray.m @@ -1,7 +1,7 @@ classdef SparseArray % Class for multi-dimensional sparse arrays. % - % Limited to arrays with a total number of elements of at most 2^48-1. + % Limited to arrays with a total number of elements of at most 2^48-1. %% Properties properties (Access = private) @@ -33,11 +33,11 @@ % Empty constructor. % % :code:`a = SparseArray(b)` - % Copies/converts :code:`b` if it is a :class:`SparseArray`, a dense array or + % Copies/converts :code:`b` if it is a :class:`.SparseArray`, a dense array or % a sparse matrix. % % :code:`a = SparseArray(b, sz)` - % Copies/converts :code:`b` if it is a :class:`SparseArray`, a dense array or + % Copies/converts :code:`b` if it is a :class:`.SparseArray`, a dense array or % a sparse matrix, and sets the size of :code:`a` to :code:`sz` % % Example @@ -145,12 +145,12 @@ % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. a.var = abs(a.var); end @@ -161,16 +161,16 @@ % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % - % tol : :class:`float` , optional + % tol : :class:`double` , optional % threshold tolerance for absolute values of entries, defaults to % :code:`1e-15`. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % sparse array with entries of absolute value below :code:`tol` set to zero. arguments a @@ -187,12 +187,12 @@ % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. a.var = conj(a.var); end @@ -210,12 +210,12 @@ % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. assert(ismatrix(a), 'sparse:RankError', 'ctranspose is only defined for 2D sparse arrays.'); a = permute(conj(a), [2, 1]); @@ -292,7 +292,7 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array % % Returns @@ -318,7 +318,7 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns @@ -333,7 +333,7 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % g : (1, :) :class:`int` % list of number of contiguous indices to be grouped in each index of the @@ -341,7 +341,7 @@ function disp(a) % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array with grouped indices. % % Example @@ -365,12 +365,12 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array with real entries corresponding to the imaginary part of the % entries of :code:`a`. a.var = imag(a.var); @@ -385,7 +385,7 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns @@ -400,13 +400,13 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- % bool : :class:`logical` - % defaults to :code:`false` for :class:`SparseArray`. + % defaults to :code:`false` for :class:`.SparseArray`. bool = false; end @@ -415,7 +415,7 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns @@ -435,18 +435,23 @@ function disp(a) function c = ldivide(a, b) % Elementwise left division for sparse arrays. % - % :code:`ldivide(a, b)` is called for the syntax :code:`a .\ b` where :code:`a` - % or :code:`b` is a :class:`SparseArray`. :code:`a`and :code:`b` must have the - % same size, unless one is a scalar. + % Usage + % ----- + % :code:`ldivide(a, b)` + % + % :code:`a .\ b` + % + % where :code:`a` or :code:`b` is a :class:`SparseArray`. :code:`a`and :code:`b` + % must have the same size, unless one is a scalar. % % Arguments % --------- - % a, b : :class:`SparseArray` or :class:`double` + % a, b : :class:`.SparseArray` or :class:`double` % input arrays to be divided. % % Returns % ------- - % c : :class:`SparseArray` + % c : :class:`.SparseArray` % elementwise left division of :code:`b` by :code:`a`. c = rdivide(b, a); end @@ -454,19 +459,24 @@ function disp(a) function c = minus(a, b) % Elementwise subtraction for sparse arrays. % - % :code:`minus(a, b)` is called for the syntax :code:`a - b` where :code:`a` - % or :code:`b` is a :class:`SparseArray`. :code:`a`and :code:`b` must have the - % same size, unless one of the is scalar. Scalar can be subtracted from a sparse - % array of any size, resulting in a dense array. + % Usage + % ----- + % :code:`minus(a, b)` + % + % :code:`a - b` + % + % where :code:`a`or :code:`b` is a :class:`.SparseArray`. :code:`a`and :code:`b` + % must have the same size, unless one of the is scalar. Scalar can be subtracted + % from a sparse array of any size, resulting in a dense array. % % Arguments % --------- - % a, b : :class:`SparseArray` or :class:`double` + % a, b : :class:`.SparseArray` or :class:`double` % intput arrays. % % Returns % ------- - % c : :class:`SparseArray` or :class:`double` + % c : :class:`.SparseArray` or :class:`double` % output array. % % Example @@ -493,14 +503,15 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % intput array. + % % b : :class:`double` % scalar to divide by. % % Returns % ------- - % c : :class:`SparseArray` + % c : :class:`.SparseArray` % output array. % % Example @@ -518,8 +529,13 @@ function disp(a) function c = mtimes(a, b) % Matrix multiplication for 2D sparse arrays. % - % :code:`mtimes(a, b)` is called for the syntax :code:`a * b` where :code:`a` - % or :code:`b` is a :class:`SparseArray`. + % Usage + % ----- + % :code:`mtimes(a, b)` + % + % :code:`a * b` + % + % where :code:`a` or :code:`b` is a :class:`.SparseArray`. % % See Also % -------- @@ -622,17 +638,18 @@ function disp(a) % % :code:`a + b` % - % :code:`a` and :code:`b` must have the same size, + % where :code:`a` and :code:`b` must have the same size, % unless one is a scalar. A scalar can be added to a sparse array of any size. % % Arguments % --------- - % a, b : :class:`SparseArray` or :class:`double` + % a, b : :class:`.SparseArray` or :class:`double` % input arrays. % % Returns % ------- - % + % c : :class:`.SparseArray` + % output array. % % Example % ------- @@ -687,18 +704,23 @@ function disp(a) function c = rdivide(a, b) % Elementwise right division for sparse arrays. % - % :code:`rdivide(a, b)` is called for the syntax :code:`a ./ b` where :code:`a` - % or :code:`b` is a :class:`SparseArray`. :code:`a`and :code:`b` must have the - % same size, unless one is a scalar. + % Usage + % ----- + % :code:`rdivide(a, b)` + % + % :code:`a ./ b` + % + % where :code:`a` or :code:`b` is a :class:`.SparseArray`. :code:`a`and + % :code:`b` must have the same size, unless one is a scalar. % % Arguments % --------- - % a, b : :class:`SparseArray` or :class:`double` + % a, b : :class:`.SparseArray` or :class:`double` % input arrays to be divided. % % Returns % ------- - % c : :class:`SparseArray` + % c : :class:`.SparseArray` % elementwise left division of :code:`a` by :code:`b`. % % Example @@ -727,12 +749,12 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array with real entries corresponding to the real part of the % entries of :code:`a`. a.var = real(a.var); @@ -798,9 +820,10 @@ function disp(a) % % Usage % ----- - % :code:`b = squeeze(a)` - % returns a sparse array :code:`b` with the same elements as :code:`a` but - % with all the singleton dimensions removed. + % :code:`b = squeeze(a)` + % + % returns a sparse array :code:`b` with the same elements as :code:`a` but + % with all the singleton dimensions removed. % % Example % ------- @@ -1006,6 +1029,7 @@ function disp(a) function varargout = svds(a, varargin) % Find a few singular values and vectors. + % % See Also % -------- % `Documentation for builtin Matlab svds `_. @@ -1017,10 +1041,15 @@ function disp(a) function c = times(a, b) % Array multiplication for sparse tensors. % - % :code:`c = times(a, b)` is called for the syntax :code:`a .* b` when :code:`a` - % or :code:`b` is a sparse array. :code:`a` and :code:`b` must have the same - % size, unless one is a scalar. A scalar can be be multiplied by a sparse array - % of any size. + % Usage + % ----- + % :code:`c = times(a, b)` + % + % :code:`a .* b` + % + % where :code:`a` or :code:`b` is a sparse array. :code:`a` and :code:`b` must + % have the same size, unless one is a scalar. A scalar can be be multiplied by + % a sparse array of any size. % % Example % ------- @@ -1054,12 +1083,12 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. assert(ismatrix(a), 'sparse:RankError', 'ctranspose is only defined for 2D sparse arrays.'); a = permute(a, [2, 1]); @@ -1076,12 +1105,12 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. a.var = -a.var; end @@ -1097,12 +1126,12 @@ function disp(a) % % Arguments % --------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % input array. % % Returns % ------- - % b : :class:`SparseArray` + % b : :class:`.SparseArray` % output array. return; end @@ -1128,7 +1157,7 @@ function disp(a) % % Returns % ------- - % a : :class:`SparseArray` + % a : :class:`.SparseArray` % output delta-array. a = SparseArray(repmat(1:inddim, numinds, 1)', 1, repmat(inddim, 1, numinds)); end @@ -1144,6 +1173,7 @@ function disp(a) % --------- % sz : (1, :) :class:`int` % size of the sparse array + % % density : :class:`double` % density of nonzero elements (0 < :code:`density` < 1) a = SparseArray([], [], sz); diff --git a/src/utility/swapvars.m b/src/utility/swapvars.m index 881ff3f..405d65d 100644 --- a/src/utility/swapvars.m +++ b/src/utility/swapvars.m @@ -4,7 +4,7 @@ % Usage % ----- % :code:`[a, b] = swapvars(a, b)` -% stores the value of a in b, and the value of b in a. +% stores the value of :code:`a` in :code:`b`, and the value of :code:`b in :code:`a`. end diff --git a/src/utility/time2str.m b/src/utility/time2str.m index 9de752f..500c996 100644 --- a/src/utility/time2str.m +++ b/src/utility/time2str.m @@ -1,5 +1,9 @@ function timeStr = time2str(time, unit, precision) -%TIMESTRING Returns string version of a duration in seconds. +% Returns string version of a duration in seconds. +% +% Usage +% ----- +% :code:`timeStr = time2str(time, unit, precision)` if nargin < 3, precision = 1; end diff --git a/src/utility/validations/mustBeEqualLength.m b/src/utility/validations/mustBeEqualLength.m index 6359ddd..b8ffbde 100644 --- a/src/utility/validations/mustBeEqualLength.m +++ b/src/utility/validations/mustBeEqualLength.m @@ -1,10 +1,11 @@ function mustBeEqualLength(a, b) -% mustBeEqualLength - Validate that the inputs are of equal length. -% mustBeEqualLength(a, b) throws an error if length(a) ~= length(b) +% Validate that the inputs are of equal length. +% +% :code:`mustBeEqualLength(a, b)` throws an error if :code:`length(a) ~= length(b)` % -% Class support: -% All classes that define these methods: -% length +% Note +% ---- +% Supported by all classes that define these methods: :code:`length` if length(a) ~= length(b) throwAsCaller(createValidatorException('TensorTrack:validators:mustBeEqualLength')); diff --git a/src/utility/validations/mustBeSorted.m b/src/utility/validations/mustBeSorted.m index 492014e..d6fec5c 100644 --- a/src/utility/validations/mustBeSorted.m +++ b/src/utility/validations/mustBeSorted.m @@ -1,10 +1,11 @@ function mustBeSorted(A) -% mustBeSorted - Validate that value is sorted. -% mustBeSorted(A) throws an error if A is not sorted. +% Validate that input is sorted. +% +% :code:`mustBeSorted(A)` throws an error if :code:`A` is not sorted. % -% Class support: -% All classes that define these methods: -% issorted +% Note +% ---- +% Supported by all classes that define these methods: :code:`issorted` if ~issorted(A) throwAsCaller(createValidatorException('TensorTrack:validators:mustBeSorted')); diff --git a/src/utility/validations/mustBeUnique.m b/src/utility/validations/mustBeUnique.m index 3a11e51..466d0d0 100644 --- a/src/utility/validations/mustBeUnique.m +++ b/src/utility/validations/mustBeUnique.m @@ -1,11 +1,11 @@ function mustBeUnique(A) -% mustBeUnique - Validate that there are no repeated values. -% mustBeUnique(A) throws an error if A contains repeated values. +% Validate that there are no repeated values. % -% Class support: -% All classes that define these methods: -% unique -% length +% :code:`mustBeUnique(A)` throws an error if :code:`A` contains repeated values. +% +% Note +% ---- +% Supported all classes that define these methods: :code:`unique`, :code:`length` if length(A) ~= length(unique(A)) throwAsCaller(createValidatorException('validators:mustBeUnique')); diff --git a/src/utility/wigner/Wigner3j.m b/src/utility/wigner/Wigner3j.m index 0a49dda..835e3af 100644 --- a/src/utility/wigner/Wigner3j.m +++ b/src/utility/wigner/Wigner3j.m @@ -1,5 +1,5 @@ function wig = Wigner3j(j1,j2,j3,m1,m2,m3,ifs,ifcb) -% Computes the Wigner $3j$ symbols +% Computes the Wigner :math:`3j` symbols % % .. math:: % @@ -49,14 +49,15 @@ % % ifcb % if exists and is true, switches to computing the Clebsch-Gordan coefficients instead of -% the $3j$-symbols (default :code:`false`) +% the :math:`3j`-symbols (default :code:`false`) % % Returns % ------- % W -% the resulting values of the 3j-symbols (:code:`ifcb=false`) or the Clebsch-Gordan -% coefficients (:code:`ifcb=true`) in either numeric double-precision or symbolic form -% (see the input parameter :code:`ifs`); array of the same size as $j_1$. +% the resulting values of the :math:`3j`-symbols (:code:`ifcb=false`) or the +% Clebsch-Gordan coefficients (:code:`ifcb=true`) in either numeric double-precision or +% symbolic form (see the input parameter :code:`ifs`); array of the same size as +% :math:`j_1`. % % % Notes @@ -71,7 +72,7 @@ % d. all the "numeric" algorithms switch automatically to the symbolic computations % as soon as the numeric overflow occurs, thereby improving the accuracy % but slowing down the computations for some big quantum numbers -% e. in cases with at least one of the $j$ quantum numbers <=2, the explicit accurate +% e. in cases with at least one of the :math:`j` quantum numbers <=2, the explicit accurate % equations are applied in all the algorithms ensuring the highest possible accuracy % f. for relatively small quantum numbers (up to ~20) all the algorithms provide % approximately equivalent results with a reasonably high accuracy diff --git a/src/utility/wigner/Wigner6j.m b/src/utility/wigner/Wigner6j.m index a14d7dc..e02f986 100644 --- a/src/utility/wigner/Wigner6j.m +++ b/src/utility/wigner/Wigner6j.m @@ -1,5 +1,5 @@ function wig = Wigner6j(j1,j2,j3,j4,j5,j6,ifs,ifcb) -% Computes the Wigner $$6j$$ symbols +% Computes the Wigner :math:`6j` symbols % % .. math:: % @@ -48,14 +48,14 @@ % % ifcb % if exists and is true, switches to computing the coupling matrix elements instead of the -% $6j$-symbols (default :code:`false`) +% :math:`6j`-symbols (default :code:`false`) % % Returns % ------- % W -% the resulting values of the 3j-symbols (:code:`ifcb=false`) or the Clebsch-Gordan +% the resulting values of the :math:`6j`-symbols (:code:`ifcb=false`) or the coupling matrix elements % coefficients (:code:`ifcb=true`) in either numeric double-precision or symbolic form -% (see the input parameter :code:`ifs`); array of the same size as $j_1$. +% (see the input parameter :code:`ifs`); array of the same size as :math:`j_1`. % % Notes % ----- @@ -69,7 +69,7 @@ % d. all the "numeric" algorithms switch automatically to the symbolic computations % e. as soon as the numeric overflow occurs, thereby improving the accuracy % but slowing down the computations for some big quantum numbers -% f. in cases with at least one of the $j$ quantum numbers <=2, the explicit accurate +% f. in cases with at least one of the :math:`j` quantum numbers <=2, the explicit accurate % equations are applied in all the algorithms ensuring the highest possible accuracy % g. for relatively small quantum numbers (up to ~20) all the algorithms provide % approximately equivalent results with a reasonably high accuracy