diff --git a/docs/src/img/Fmove.svg b/docs/src/img/Fmove.svg index a346b90..b995591 100644 --- a/docs/src/img/Fmove.svg +++ b/docs/src/img/Fmove.svg @@ -1,5 +1,5 @@ - + @@ -9,293 +9,252 @@ - + - - - - - - - + - + - + - - - - - - - - - - - - - - - - - + + - - + + - + - + - + - + - + + + + + + + - + - + - + - + - - - - - - - - - - - - - - - - + - + - + - - - - + - - - - - + + - - + + - - + + - + - - - - - - - - - - - - - - + + - + - - - - - - - + - - - - - - - - + + - - + + - - + + - - + + + + + + + + + + + - + + + + + + + - + - + + - + + - + + - - - - - - - - - - - - - - + + + - + - + - + - + - - - - - - - - - - - - - - - - - - + + - + - - + + + + - - - - - + - - + - + + + - + - - - - - + - + - + - - - + + + - + - + - + + + + - - - - + + + + + + + + + + + + + + + + + - + + - + + + + + + + + + + + + + + + + + - - - - + + + - + + diff --git a/docs/src/img/Rmove.svg b/docs/src/img/Rmove.svg index fd76809..bc1d285 100644 --- a/docs/src/img/Rmove.svg +++ b/docs/src/img/Rmove.svg @@ -1,5 +1,5 @@ - + @@ -8,168 +8,168 @@ - - - - + - + - + + + + - + - - - - + - + - + - + - + - - - - - - - - - - + - - - - - + + - + - + + + + - + - - - - + - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + - + - + + - + + + - + + - - - - - - - - - - - + + + + + + + + + + + + - + + + - + - - - - - - - - - - + + + + + + + + + + + + - + + - + - + - + - + - + - - + + - + - + - + - + + - + + - + diff --git a/docs/src/img/fusiontensor.svg b/docs/src/img/fusiontensor.svg index 3fdeadd..89fa76c 100644 --- a/docs/src/img/fusiontensor.svg +++ b/docs/src/img/fusiontensor.svg @@ -1,5 +1,5 @@ - + @@ -9,44 +9,51 @@ + + + - - - - - - + + + + + + - + - + + - + + + - - - - - - - - - - - - + + + + + + + + + + + + + - + diff --git a/docs/src/img/ipe/Fmove.pdf b/docs/src/img/ipe/Fmove.pdf index 8752498..cf14649 100644 Binary files a/docs/src/img/ipe/Fmove.pdf and b/docs/src/img/ipe/Fmove.pdf differ diff --git a/docs/src/img/ipe/conv.sh b/docs/src/img/ipe/conv.sh new file mode 100755 index 0000000..d2eeacc --- /dev/null +++ b/docs/src/img/ipe/conv.sh @@ -0,0 +1,5 @@ +#!/bin/bash +for i in *.pdf +do + pdf2svg ${i%.*}.pdf ../${i%.*}.svg all +done diff --git a/docs/src/index.rst b/docs/src/index.rst index 41126a0..9a63f69 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -16,9 +16,9 @@ Additionally, for tensors which are invariant under general global symmetries, v :caption: Manual :maxdepth: 2 - man/intro man/tensor man/symmetries + man/algorithms .. toctree:: @@ -33,5 +33,10 @@ Additionally, for tensors which are invariant under general global symmetries, v :maxdepth: 2 lib/tensors + lib/sparse + lib/mps + lib/environments + lib/algorithms + lib/models lib/utility lib/caches diff --git a/docs/src/lib/algorithms.rst b/docs/src/lib/algorithms.rst new file mode 100644 index 0000000..446c01d --- /dev/null +++ b/docs/src/lib/algorithms.rst @@ -0,0 +1,50 @@ +Algorithms +========== + +.. toctree:: + :maxdepth: 2 + +.. module:: src + +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 new file mode 100644 index 0000000..cde31f8 --- /dev/null +++ b/docs/src/lib/environments.rst @@ -0,0 +1,12 @@ +Environments +============ + +.. toctree:: + :maxdepth: 2 + +.. module:: src + +This section contains the API documentation for the :mod:`.environments` module. + +.. autoclass:: src.environments.FiniteEnvironment + diff --git a/docs/src/lib/models.rst b/docs/src/lib/models.rst new file mode 100644 index 0000000..6854de1 --- /dev/null +++ b/docs/src/lib/models.rst @@ -0,0 +1,39 @@ +Models +====== + +.. toctree:: + :maxdepth: 2 + +.. module:: src + +This section contains the API documentation for the :mod:`.models` module. + +.. 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 new file mode 100644 index 0000000..53e7d7e --- /dev/null +++ b/docs/src/lib/mps.rst @@ -0,0 +1,30 @@ +MPS +=== + +.. toctree:: + :maxdepth: 2 + +.. module:: src + +This section contains the API documentation for the :mod:`.mps` module. + +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 new file mode 100644 index 0000000..7593aff --- /dev/null +++ b/docs/src/lib/sparse.rst @@ -0,0 +1,12 @@ +Sparse +====== + +.. toctree:: + :maxdepth: 2 + +.. module:: src + +This section contains the API documentation for the :mod:`.sparse` module. + +.. autoclass:: src.sparse.SparseTensor + :no-members: diff --git a/docs/src/lib/tensors.rst b/docs/src/lib/tensors.rst index 9f5278e..3df31a7 100644 --- a/docs/src/lib/tensors.rst +++ b/docs/src/lib/tensors.rst @@ -12,7 +12,35 @@ This section contains the API documentation for the :mod:`.tensors` module. Symmetry sectors ---------------- -.. automodule:: src.tensors.charges +Type hierarchy +`````````````` + +.. autoclass:: src.tensors.charges.AbstractCharge +.. autoclass:: src.tensors.charges.FusionStyle +.. autoclass:: src.tensors.charges.BraidingStyle +.. autoclass:: src.tensors.charges.ProductCharge + + +Concrete charge types +````````````````````` + +.. autoclass:: src.tensors.charges.Z1 +.. autoclass:: src.tensors.charges.Z2 +.. autoclass:: src.tensors.charges.ZN +.. autoclass:: src.tensors.charges.fZ2 +.. autoclass:: src.tensors.charges.U1 +.. autoclass:: src.tensors.charges.fU1 +.. autoclass:: src.tensors.charges.SU2 +.. autoclass:: src.tensors.charges.fSU2 +.. autoclass:: src.tensors.charges.SUN +.. autoclass:: src.tensors.charges.O2 +.. autoclass:: src.tensors.charges.A4 + + +Helper routines +``````````````` + +.. autoclass:: src.tensors.charges.GtPattern Fusion trees @@ -24,16 +52,49 @@ Fusion trees Spaces ------ -.. automodule:: src.tensors.spaces +Type hierarchy +`````````````` + +.. autoclass:: src.tensors.spaces.AbstractSpace +.. autoclass:: src.tensors.spaces.SumSpace + + +Concrete space types +```````````````````` + +.. autoclass:: src.tensors.spaces.CartesianSpace +.. autoclass:: src.tensors.spaces.ComplexSpace +.. autoclass:: src.tensors.spaces.GradedSpace + + +Convenience constructor wrappers +```````````````````````````````` + +.. autofunction:: src.tensors.spaces.Z2Space +.. autofunction:: src.tensors.spaces.fZ2Space +.. autofunction:: src.tensors.spaces.U1Space +.. autofunction:: src.tensors.spaces.SU2Space + +Helper classes +`````````````` + +.. autoclass:: src.tensors.spaces.Arrow Kernels ------- -.. automodule:: src.tensors.kernels +.. autoclass:: src.tensors.kernels.AbstractBlock +.. autoclass:: src.tensors.kernels.TrivialBlock + :no-members: +.. autoclass:: src.tensors.kernels.MatrixBlock + :no-members: +.. autoclass:: src.tensors.kernels.AbelianBlock + :no-members: Tensors ------- +.. autoclass:: src.tensors.AbstractTensor .. autoclass:: src.tensors.Tensor 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/docs/src/man/algorithms.rst b/docs/src/man/algorithms.rst new file mode 100644 index 0000000..faca9a3 --- /dev/null +++ b/docs/src/man/algorithms.rst @@ -0,0 +1,4 @@ +Algorithms +========== + +Coming soon. diff --git a/docs/src/man/symmetries.rst b/docs/src/man/symmetries.rst index 07f3df8..de1c5a6 100644 --- a/docs/src/man/symmetries.rst +++ b/docs/src/man/symmetries.rst @@ -1,2 +1,4 @@ Symmetries ========== + +Coming soon. diff --git a/docs/src/man/tensor.rst b/docs/src/man/tensor.rst index 14c9ebb..a27e587 100644 --- a/docs/src/man/tensor.rst +++ b/docs/src/man/tensor.rst @@ -1,10 +1,10 @@ -Tensor manipulations -==================== +Tensors and tensor manipulations +================================ Definitions ----------- -We start with the definition of a tensor. According to the `Link Wikipedia page ` on tensors, there are 3 equivalent ways of describing a tensor object: +We start with the definition of a tensor. According to the `Wikipedia page `_ on tensors, there are 3 equivalent ways of describing a tensor object: * As a multidimensional array. 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..12e5d65 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..b6b51cf 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..9880ec8 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..a936b22 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 0c99587..c90f8db 100644 --- a/src/mps/MpoTensor.m +++ b/src/mps/MpoTensor.m @@ -1,15 +1,22 @@ classdef (InferiorClasses = {?Tensor, ?MpsTensor, ?SparseTensor}) MpoTensor < AbstractTensor - % Matrix product operator building block - % This object represents the MPO tensor at a single site as the sum of rank (2,2) - % (sparse) tensors and some scalars, which will be implicitly used as unit tensors. + % Matrix product operator building block. + % + % This object represents the MPO tensor at a single site as the sum of rank (2,2) + % (sparse) tensors and some scalars, which will be implicitly used as unit tensors. + % + % .. code-block:: % % 4 - % ^ + % v % | - % 1 ->-- O -->- 3 + % 1 -<-- O --<- 3 % | - % ^ + % v % 2 + % + % Todo + % ---- + % Document. properties tensors = [] @@ -440,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 % ----- @@ -448,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..7ab6db4 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,39 +940,16 @@ 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) - - end %% 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 +1053,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/AbstractTensor.m b/src/tensors/AbstractTensor.m index 9680142..8929afc 100644 --- a/src/tensors/AbstractTensor.m +++ b/src/tensors/AbstractTensor.m @@ -1,35 +1,40 @@ classdef AbstractTensor - + % Abstract base class for representing tensors. + % + % See Also + % -------- + % :class:`.Tensor`, :class:`.SparseTensor`, :class:`.MpsTensor` and + % :class:`.MpoTensor` methods function varargout = linsolve(A, b, x0, M1, M2, options) - % Find a solution for a linear system `A(x) = b` or `A * x = b`. + % Find a solution for a linear system :code:`A(x) = b` or :code:`A * x = b`. % % Arguments % --------- - % A : operator + % A : :class:`.AbstractTensor` or :class:`function_handle` % either a function handle implementing or an object that supports % right multiplication. % - % b : :class:`Tensor` + % b : :class:`.AbstractTensor` % right-hand side of the equation, interpreted as vector. % - % x0 : :class:`Tensor` + % x0 : :class:`.AbstractTensor` % optional initial guess for the solution. % - % M1, M2 : operator - % preconditioner M = M1 or M = M1 * M2 to effectively solve the system A * - % inv(M) * y = b with y = M * x. - % M is either a function handle implementing or an object that supports - % left division. + % M1, M2 : :class:`.AbstractTensor` or :class:`function_handle` + % preconditioner :code:`M = M1` or :code:`M = M1 * M2` to effectively solve + % the system :code:`A * inv(M) * y = b` with :code:`y = M * x`. + % :code:`M` is either a function handle implementing or an object that + % supports left division. % % Keyword Arguments % ----------------- - % Tol : numeric + % Tol : :class:`numeric` % specifies the tolerance of the method, by default this is the square root of % eps. % - % Algorithm : char + % Algorithm : :class:`char` % specifies the algorithm used. Can be either one of the following: % % - 'bicgstab' @@ -37,13 +42,13 @@ % - 'gmres' % - 'pcg' % - % MaxIter : int + % MaxIter : :class:`int` % Maximum number of iterations. % - % Restart : int + % Restart : :class:`int` % For 'gmres', amount of iterations after which to restart. % - % Verbosity : int + % Verbosity : :class:`int` % Level of output information, by default nothing is printed if `flag` is % returned, otherwise only warnings are given. % @@ -53,10 +58,10 @@ % % Returns % ------- - % x : :class:`Tensor` + % x : :class:`.AbstractTensor` % solution vector. % - % flag : int + % flag : :class:`int` % a convergence flag: % % - 0 : linsolve converged to the desired tolerance. @@ -65,13 +70,13 @@ % - 3 : linsolve stagnated. % - 4 : one of the scalar quantities calculated became too large or too small. % - % relres : numeric + % relres : :class:`numeric` % relative residual, norm(b - A * x) / norm(b). % - % iter : int + % iter : :class:`int` % iteration number at which x was computed. % - % resvec : numeric + % resvec : :class:`numeric` % vector of estimated residual norms at each part of the iteration. arguments @@ -159,28 +164,29 @@ % Usage % ----- % :code:`[V, D, flag] = eigsolve(A, x0, howmany, sigma, kwargs)` + % % :code:`D = eigsolve(A, x0, ...)` % % Arguments % --------- - % A : :class:`Tensor` or function_handle + % A : :class:`.AbstractTensor` or :class:`function_handle` % A square tensormap interpreted as 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 % - % x0 : :class:`Tensor` - % 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 + % x0 : :class:`.AbstractTensor` + % 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 @@ -197,28 +203,28 @@ % % Keyword Arguments % ----------------- - % Tol : numeric + % Tol : :class:`numeric` % 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 + % 'KrylovSchur', or the use of a custom Arnoldi 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 - % Level of output information, by default nothing is printed if `flag` is - % returned, otherwise only warnings are given. + % Verbosity : :class:`int` + % Level of output information, by default nothing is printed if :code:`flag` + % is returned, otherwise only warnings are given. % % - 0 : no information % - 1 : information at failure @@ -227,15 +233,15 @@ % % Returns % ------- - % V : (1, howmany) :class:`Tensor` + % V : (1, :code:`howmany`) :class:`.AbstractTensor` % 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 - % if flag = 0 then all eigenvalues are converged, otherwise not. + % flag : :class:`int` + % if :code:`flag = 0` then all eigenvalues are converged, otherwise not. arguments A @@ -411,11 +417,11 @@ function disp(t, details) % % Arguments % --------- - % A, B : :class:`Tensor` + % A, B : :class:`.AbstractTensor` % % Returns % ------- - % d : numeric + % d : :class:`numeric` % Euclidean distance, defined as the norm of the distance. n = max(ndims(A), ndims(B)); @@ -438,14 +444,14 @@ function disp(t, details) % % 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-12} diff --git a/src/tensors/FusionTree.m b/src/tensors/FusionTree.m index 91cf0dc..6a2943b 100644 --- a/src/tensors/FusionTree.m +++ b/src/tensors/FusionTree.m @@ -3,16 +3,16 @@ % % Properties % ---------- - % charges : :class:`AbstractCharge` + % charges : (:, :) :class:`.AbstractCharge` % labels for the edges of the fusion trees % - % vertices : int + % vertices : (:, :) :class:`int` % labels for the vertices of the fusion trees % - % isdual : logical + % isdual : (1, :) :class:`logical` % indicator of duality transform on the external edges. % - % rank : int + % rank : (1, 2) :class:`int` % amount of splitting tree and fusion tree legs. properties @@ -37,18 +37,18 @@ % % Arguments % --------- - % charges : :class:`AbstractCharge` + % charges : (:, :) :class:`.AbstractCharge` % array of charges, where each row represents an allowed fusion channel. % - % vertices : int = [] + % vertices (:, :) : :class:`.int` % Array of vertex labels. Must be empty or have the same amount of % rows as `charges`. This is optional if the charges have a fusion style % which is multiplicity-free. % - % isdual : logical + % isdual : (1, :) :class:`logical` % mask that shows the presence of duality transformations. % - % rank : int + % rank : (1, 2) :class:`int` % number of splitting and fusing legs. if nargin == 0 @@ -88,15 +88,15 @@ % % Arguments % --------- - % rank : int + % rank : (1, 2) :class:`int` % number of legs for the splitting and fusion tree. % % Repeating Arguments % ------------------- - % charges : :class:`AbstractCharge` + % charges : (1, :) :class:`.AbstractCharge` % set of charges for a given leg % - % isdual : logical + % isdual : :class:`logical` % presence of a duality transform arguments @@ -238,23 +238,23 @@ % % Arguments % --------- - % f : :class:`FusionTree` - % tree to swap. + % f : :class:`.FusionTree` + % tree to swap % - % i : int - % `i` and `i+1` are the braided strands. + % i : :class:`int` + % :code:`i` and :code:`i+1` are the braided strands % - % inv : logical = false - % flag to indicate whether to perform an overcrossing (false) or an - % undercrossing (true). + % inv : :class:`logical` = :code:`false` + % flag to indicate whether to perform an overcrossing (:code:`false`) or an + % undercrossing (:code:`true`) % % Returns % ------- - % c : sparse double - % matrix of coefficients that transform input to output trees. - % f(i) --> c(i,j) * f(j) + % c : (:, :) :class:`sparse` + % matrix of coefficients that transform input to output trees: + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % braided trees in canonical form. if nargin < 3, inv = false; end @@ -410,16 +410,16 @@ % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % tree to bend. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % f(i) --> c(i,j) * f(j) + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % bent trees in canonical form. f = flip(f); @@ -434,16 +434,16 @@ % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % tree to bend. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % `f(i) --> c(i,j) * f(j)` + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % bent trees in canonical form. if ~hasmultiplicity(fusionstyle(f)) @@ -544,30 +544,31 @@ function [c, f] = braid(f, p, lvl, rank) % Compute the coefficients that bring a braided tree into canonical form. - % This is done by reducing the braid into a composition of elementary swaps - % on neighbouring strands. + % + % This is done by reducing the braid into a composition of elementary swaps + % on neighbouring strands. % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % tree to braid. % - % p : int + % p : (:, :) :class:`int` % permutation indices. % - % lvl : int + % lvl : (:, :) :class:`int` % height of the strands, indicating over- and undercrossings. % - % rank : int + % rank : :class:`int` (1, 2) % final number of splitting and fusing legs. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % f(i) --> c(i,j) * f(j) + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % braided trees in canonical form. % % Todo @@ -717,19 +718,19 @@ % f : :class:`FusionTree` % tree to permute. % - % p : int + % p : (1, :) :class:`int` % permutation indices. % - % r : int + % r : (1, 2) :class:`int` % final number of splitting and fusing legs. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % `f(i) --> c(i,j) * f(j)` + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % permuted trees in canonical form. arguments @@ -749,19 +750,19 @@ % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % tree to repartition. % - % newrank : int + % newrank : (1, 2) :class:`int` % new rank of the fusion tree. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % `f(i) --> c(i,j) * f(j)` + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % repartitioned trees in canonical form. arguments @@ -799,22 +800,22 @@ % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % tree to repartition. % - % i : int or logical + % i : :class:`int` or :class:`logical` % indices of legs to twist. % - % inv : logical + % inv : :class:`logical` % flag to determine inverse twisting. % % Returns % ------- - % c : sparse double + % c : (:, :) :class:`sparse` % matrix of coefficients that transform input to output trees. - % `f(i) --> c(i,j) * f(j)` + % :code:`f(i) --> c(i,j) * f(j)` % - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % twisted trees in canonical form. arguments @@ -1138,11 +1139,11 @@ function displayNonScalarObject(f) % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % % Returns % ------- - % A : double + % A : :class:`double` % array representation of a fusion tree. assert(issymmetric(braidingstyle(f)), ... @@ -1176,13 +1177,13 @@ function displayNonScalarObject(f) % % Arguments % --------- - % f : :class:`FusionTree` + % f : :class:`.FusionTree` % an array of fusion trees to convert. % % Returns % ------- - % C : cell - % a cell array containing the array representations of f. + % C : :class:`cell` + % a cell array containing the array representations of :code:`f`. if fusionstyle(f) == FusionStyle.Unique C = num2cell(ones(size(f))); diff --git a/src/tensors/Tensor.m b/src/tensors/Tensor.m index 99da0c0..b9d1d98 100644 --- a/src/tensors/Tensor.m +++ b/src/tensors/Tensor.m @@ -1,5 +1,20 @@ classdef Tensor < AbstractTensor - % Tensor - Base implementation of a dense tensor array with optional symmetries. + % Base implementation of a dense tensor array with optional symmetries. + % + % Properties + % ---------- + % codomain + % codomain vector space represented as tensor product space. + % + % domain + % codomain vector space represented as tensor product space. + % + % var + % block sparse representation of tensor data. + % + % Todo + % ---- + % Document all methods. properties codomain @@ -23,10 +38,10 @@ % % Arguments % --------- - % array : numeric + % array : :class:`numeric` % numeric input array to convert to a :class:`Tensor` % - % codomain, domain : :class:`AbstractSpace` + % codomain, domain : (1, :) :class:`.AbstractSpace` % spaces that define the structure of the output tensor. % % Returns @@ -109,21 +124,21 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to fill into. % - % matrices : cell or numeric + % matrices : :class:`cell` or :class:`numeric` % list of matrices or single matrix to fill with. % % fun : :class:`function_handle` % function of signature :code:`fun(dims, charge)` to fill with. % - % charges : :class:`AbstractCharge` + % charges : :class:`.AbstractCharge` % optional list of charges to identify the matrix blocks. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % filled tensor. arguments @@ -160,10 +175,10 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to fill into. % - % tensors : cell or numeric + % tensors : :class:`cell` or :class:`numeric` % list of tensors or single tensor to fill with. % % fun : :class:`function_handle` @@ -171,7 +186,7 @@ % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % filled tensor. arguments @@ -208,7 +223,7 @@ % % Repeating Arguments % ------------------- - % tensors : :class:`Tensor` + % tensors : :class:`.Tensor` % input tensors used to copy legs. % % indices : int @@ -216,22 +231,22 @@ % % Keyword Arguments % ----------------- - % Rank : (1, 2) int + % Rank : (1, 2) :class:`int´ % rank of the output tensor, by default this is :code:`[nspaces(t) 0]`. % - % Conj : logical + % Conj : :class:`logical` % flag to indicate whether the space should be equal to the input space, or % fit onto the input space. This can be either an array of size(tensors), or a % scalar, in which case it applies to all tensors. % - % Mode : 'tensor' or 'matrix' + % Mode : :class:`char`, 'tensor' or 'matrix' % method of filling the tensor data. By default this is matrix, where the % function should be of signature :code:`fun(dims, charge)`, for 'tensor' this % should be of signature :code:`fun(dims, tree)`. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. % % Examples @@ -300,39 +315,39 @@ % function of signature :code:`fun(dims, id)` where id is determined by Mode. % If this is left empty, the tensor data will be uninitialized. % - % dims : int + % dims : :class:`int` % list of dimensions for non-symmetric tensors. % - % arrows : logical + % arrows : :class:`logical` % optional list of arrows for tensor legs. % - % tensor : :class:`Tensor` + % tensor : :class:`.Tensor` % input tensor to copy structure. % % Repeating Arguments % ------------------- - % charges : cell + % charges : :class:`cell` % list of charges for each tensor index. % - % degeneracies : cell + % degeneracies : :class:`cell` % list of degeneracies for each tensor index. % - % arrow : logical + % arrow : :class:`logical` % arrow for each tensor index. % % Keyword Arguments % ----------------- - % Rank : int (1, 2) - % rank of the constructed tensor. By default this is [nspaces(t) 0]. + % Rank : (1, 2) :class:`int` + % rank of the constructed tensor. By default this is :code:`[nspaces(t) 0]`. % - % Mode : 'matrix' or 'tensor' + % Mode : :class:`char`, 'matrix' or 'tensor' % method of filling the resulting tensor. When this is 'matrix' (default), % the function signature is :code:`fun(dims, charge)`, while for 'tensor' the % signature should be :code:`fun(dims, tree)`. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. arguments @@ -495,7 +510,19 @@ end function tdst = insert_onespace(tsrc, i, dual) - % insert a trivial space at position i. + % 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 @@ -516,7 +543,7 @@ end function tdst = embed(tsrc, tdst) - % embed a tensor in a different tensor. + % Embed a tensor in a different tensor. assert(isequal(rank(tsrc), rank(tdst)), 'tensors:argerror', ... 'tensors must have the same rank'); @@ -553,12 +580,12 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % conjugate tensor. for i = 1:numel(t) @@ -573,16 +600,17 @@ % Usage % ----- % :code:`t = ctranspose(t)` + % % :code:`t = t'` % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % adjoint tensor. for i = 1:numel(t) @@ -600,12 +628,12 @@ % % Arguments % --------- - % t1, t2 : :class:`Tensor` + % t1, t2 : :class:`.Tensor` % tensors of equal structure. % % Returns % ------- - % d : double + % d : :class:`double` % scalar dot product of the two tensors. assert(isequal(size(t1), size(t2)), 'tensors:dimerror', ... @@ -631,12 +659,12 @@ % % Arguments % --------- - % t1, t2 : :class:`Tensor` or numeric + % t1, t2 : :class:`.Tensor` or :class:`numeric` % input tensors, scalars are interpreted as scalar * eye. % % Returns % ------- - % t1 : :class:`Tensor` + % t1 : :class:`.Tensor` % output tensor if isnumeric(t1), t1 = t1 + (-t2); return; end @@ -672,12 +700,12 @@ % % Arguments % --------- - % t1, t2 : :class:`Tensor` or numeric + % t1, t2 : :class:`.Tensor` or :class:`numeric` % input tensor or scalar. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. t = inv(t1) * t2; @@ -694,12 +722,12 @@ % % Arguments % --------- - % t1, t2 : :class:`Tensor` or numeric + % t1, t2 : :class:`.Tensor` or :class:`numeric` % input tensor or scalar. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. t = t1 * inv(t2); @@ -716,12 +744,12 @@ % % Arguments % --------- - % A, B : :class:`Tensor` - % input tensors, satisfying A.domain = B.codomain. + % A, B : :class:`.Tensor` + % input tensors, satisfying :code:`A.domain == B.codomain`. % % Returns % ------- - % C : :class:`Tensor` + % C : :class:`.Tensor` % output tensor. if isscalar(A) || isscalar(B) @@ -793,10 +821,10 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor, considered as a matrix from domain to codomain. % - % p : 1, 2, inf or 'fro' + % p : 1, 2, 'inf' or 'fro' % type of norm to compute % % Returns @@ -883,18 +911,18 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % p : (1, :) int + % p : (1, :) :class:`int` % permutation vector, by default a trivial permutation. % - % r : (1, 2) int + % r : (1, 2) :class:`int` % rank of the output tensor, by default equal to the rank of the input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % permuted tensor with desired rank. arguments @@ -949,10 +977,11 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % r : (1, 2) int + % r : (1, 2) :class:`int` + % rank of the output tensor, by default equal to :code:`[nspaces(t) 0]`. % % Returns % ------- @@ -982,10 +1011,10 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. - % uminus - % a : numeric + % + % a : :class:`numeric` % input scalar. % % Returns @@ -1047,20 +1076,20 @@ % % Arguments % --------- - % A, B : :class:`Tensor` - % input tensors, must satisfy space(A, dimA) = conj(space(B, dimB)). + % A, B : :class:`.Tensor` + % input tensors, must satisfy :code:`space(A, dimA) == conj(space(B, dimB))`. % - % dimA, dimB : (1, :) int + % dimA, dimB : (1, :) :class:`int` % selected indices to contract. % % Keyword Arguments % ----------------- - % NumDimensionsA : int + % NumDimensionsA : :class:`int` % number of spaces of A, to satisfy builtin tensorprod syntax. % % Returns % ------- - % C : :class:`Tensor` or numeric + % C : :class:`.Tensor` or :class:`numeric` % output tensor, with the uncontracted spaces of A as codomain, and the % uncontracted spaces of B as domain, or output scalar, if no uncontracted % spaces remain. @@ -1221,20 +1250,20 @@ % Usage % ----- % :code:`t = times(t, a)` - % :code:`t uminus= t .* a` + % % :code:`t = a .* t` % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % a : numeric + % a : :class:`numeric` % input scalar. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. if isscalar(A) && ~isscalar(B) @@ -1289,12 +1318,12 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor, considered as a matrix from domain to codomain. % % Returns % ------- - % tr : double + % tr : :class:`double` % matrix trace of the tensor. tr = 0; @@ -1314,22 +1343,23 @@ % Usage % ----- % :code:`t = transpose(t, p, rank)` + % % :code:`t = t.'` % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`:Tensor` % input tensor. % - % p : (1, :) int + % p : (1, :) :class:`int` % permutation vector, which must be cyclic. By default this is no permutation. % - % r : (1, 2) int + % r : (1, 2) :class:`int` % rank of the output tensor, by default equal to the rank of the input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % transposed output tensor. if nargin < 2 p = circshift(1:nspaces(t), length(t.domain)); @@ -1349,18 +1379,18 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % i : (1, :) int or logical + % i : (1, :) :class:`int` or :class:`logical` % indices to twist. % - % inv : logical + % inv : :class:`logical` % flag to indicate inverse twisting. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % twisted tensor with desired rank. arguments @@ -1403,18 +1433,18 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % i : (1, :) int or logical + % i : (1, :) :class:`int` or :class:`logical` % indices to twist. % - % inv : logical + % inv : :class:`logical` % flag to indicate inverse twisting. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % twisted tensor with desired rank. arguments t @@ -1455,19 +1485,19 @@ % % Arguments % --------- - % A : :class:`Tensor` + % A : :class:`.Tensor` % square input tensor. % % Returns % ------- - % D : (:,:) :class:`Tensor` + % D : (:, :) :class:`.Tensor` % diagonal matrix of eigenvalues. % - % V : (1,:) :class:`Tensor` - % row vector of right eigenvectors such that A * V = V * D. + % V : (1, :) :class:`.Tensor` + % row vector of right eigenvectors such that :code:`A * V = V * D`. % - % W : (1,:) :class:`Tensor` - % row vector of left eigenvectors such that W' * A = D * W'. + % W : (1, :) :class:`Tensor` + % row vector of left eigenvectors such that :code:`W' * A = D * W'`. assert(isequal(A.codomain, A.domain), 'tensors:ArgumentError', ... 'Input should be square.'); @@ -1526,30 +1556,30 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to factorize. % - % p1, p2 : int + % p1, p2 : :class:`int` % partition of left and right indices, by default this is the partition of the % input tensor. % - % alg : char or string + % 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. + % - :code:`'qr'` produces an upper triangular remainder R + % - :code:`'qrpos'` corrects the diagonal elements of R to be positive. + % - :code:`'ql'` produces a lower triangular remainder R + % - :code:`'qlpos'` corrects the diagonal elements of R to be positive. + % - :code:`'polar'` produces a Hermitian and positive semidefinite R. + % - :code:`'svd'` uses a singular value decomposition. % % Returns % ------- - % Q : :class:`Tensor` - % Orthonormal basis tensor + % Q : :class:`.Tensor` + % orthonormal basis tensor. % - % R : :class:`Tensor` - % Remainder tensor, depends on selected algorithm. + % R : :class:`.Tensor` + % remainder tensor, depends on selected algorithm. arguments t @@ -1607,29 +1637,29 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to factorize. % - % p1, p2 : int + % p1, p2 : :class:`int` % partition of left and right indices, by default this is the partition of the % input tensor. % - % alg : char or string + % 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. + % - :code:`'rq'` produces an upper triangular remainder R + % - :code:`'rqpos'` corrects the diagonal elements of R to be positive. + % - :code:`'lq'` produces a lower triangular remainder R + % - :code:`'lqpos'` corrects the diagonal elements of R to be positive. + % - :code:`'polar'` produces a Hermitian and positive semidefinite R. + % - :code:`'svd'` uses a singular value decomposition. % % Returns % ------- - % R : :class:`Tensor` + % R : :class:`.Tensor` % Remainder tensor, depends on selected algorithm. % - % Q : :class:`Tensor` + % Q : :class:`.Tensor` % Orthonormal basis tensor. arguments @@ -1683,22 +1713,22 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to compute the nullspace. % - % p1, p2 : int + % p1, p2 : :class:`int` % partition of left and right indices, by default this is the partition of the % input tensor. % - % alg : char or string + % alg : :class:`char` or :class:`string` % selection of algorithms for the nullspace: % - % - 'svd' - % - 'qr' + % - :code:`'svd'` + % - :code:`'qr'` % % Returns % ------- - % N : :class:`Tensor` + % N : :class:`.Tensor` % orthogonal basis for the left nullspace. arguments @@ -1753,22 +1783,22 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor to compute the nullspace. % - % p1, p2 : int + % p1, p2 : :class:`int` % partition of left and right indices, by default this is the partition of the % input tensor. % - % alg : char or string + % alg : :class:`char` or :class:`string` % selection of algorithms for the nullspace: % - % - 'svd' - % - 'lq' + % - :code:`'svd'` + % - :code:`'lq'` % % Returns % ------- - % N : :class:`Tensor` + % N : :class:`.Tensor` % orthogonal basis for the right nullspace. arguments @@ -1846,41 +1876,43 @@ % % Usage % ----- - % [U, S, V] = tsvd(t, p1, p2) - % [U, S, V, eta] = tsvd(t, p1, p2, trunc, tol) - % S = tsvd(t, ...) + % :code:`[U, S, V] = tsvd(t, p1, p2)` + % + % :code:`[U, S, V, eta] = tsvd(t, p1, p2, trunc, tol)` + % + % :code:`S = tsvd(t, ...)` % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % p1, p2 : int + % p1, p2 : :class:`int` % partition of left and right indices, by default this is the partition of the % input tensor. % % Keyword Arguments % ----------------- - % TruncDim : int + % TruncDim : :class:`int` % truncate such that the dim of S is not larger than this value for any given % charge. % - % TruncTotalDim : int + % TruncTotalDim : :class:`int` % truncate such that the total dim of S is not larger than this value. % - % TruncBelow : numeric + % TruncBelow : :class:`numeric` % truncate such that there are no singular values below this value. % - % TruncSpace : :class:`AbstractSpace` + % TruncSpace : :class:`.AbstractSpace` % truncate such that the space of S is smaller than this value. % % Returns % ------- - % U, S, V : :class:`Tensor` + % U, S, V : :class:`.Tensor` % left isometry U, non-negative diagonal S and right isometry V that satisfy % :code:`U * S * V = tpermute(t, [p1 p2], [length(p1) length(p2)])`. % - % eta : numeric + % eta : :class:`numeric` % truncation error. arguments @@ -1999,12 +2031,12 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. assert(isequal(t.codomain, t.domain), 'tensors:ArgumentError', ... @@ -2018,16 +2050,17 @@ end function t = inv(t) - % Compute the matrix inverse of a square tensor, such that t * inv(t) = I. + % Compute the matrix inverse of a square tensor, such that + % :code:`t * inv(t) = I`. % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % Returns % ------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % output tensor. assert(isisometric(t.codomain, t.domain), 'tensors:ArgumentError', ... @@ -2051,22 +2084,22 @@ % % Usage % ----- - % :class:`A = x^Y` + % :code:`A = x^Y` % - % :class:`A = X^y` + % :code:`A = X^y` % % Arguments % --------- - % X, Y : :class:`Tensor` - % Square input tensor. + % X, Y : :class:`.Tensor` + % square input tensor. % - % x, y : numeric - % Input scalars. + % x, y : :class:`numeric` + % input scalars. % % Returns % ------- - % A : :class:`Tensor` - % Output tensor. + % A : :class:`.Tensor` + % output tensor. % tensor to a scalar power if isnumeric(Y) && isscalar(Y) @@ -2100,22 +2133,23 @@ function [A, resnorm] = sqrtm(A) % Compute the principal square root of a square tensor. This is the unique root - % for which every eigenvalue has nonnegative real part. If `t` is singular, then - % the result may not exist. + % for which every eigenvalue has nonnegative real part. If :code:`t` is + % singular, then the result may not exist. % % Arguments % --------- - % A : :class:`Tensor` + % A : :class:`.Tensor` % input tensor. % % Returns % ------- - % X : :class:`Tensor` - % principal square root of the input, which has X^2 = A. + % X : :class:`.Tensor` + % principal square root of the input, which has :code:`X^2 = A`. % - % resnorm : numeric - % the relative residual, norm(A - X^2, 1) / norm(A, 1). If this argument is - % returned, no warning is printed if exact singularity is detected. + % resnorm : :class:`numeric` + % the relative residual, :code:`norm(A - X^2, 1) / norm(A, 1)`. If this + % argument is returned, no warning is printed if exact singularity is + % detected. assert(isequal(A.codomain, A.domain), 'tensors:ArgumentError', ... 'Input should be square.'); @@ -2145,19 +2179,19 @@ % nonzero complex column vector `z`. % This is equivalent to any of the following conditions: % - % - M is Hermitian and all eigenvalues are real and positive. - % - M is congruent with a diagonal matrix with positive real entries. - % - There exists an invertible B such that `M = B' * B`. + % - `M` is Hermitian and all eigenvalues are real and positive. + % - `M` is congruent with a diagonal matrix with positive real entries. + % - There exists an invertible `B` such that `M = B' * B`. % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % Returns % ------- - % bool : logical - % true if `t` is positive definite. + % bool : :class:`logical` + % true if :code:`t` is positive definite. mblocks = matrixblocks(t); for i = 1:length(mblocks) @@ -2175,22 +2209,22 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % - % side : char + % side : :class:`char` % either 'left', 'right' or 'both' (default). % % Keyword Arguments % ----------------- - % AbsTol, RelTol : numeric - % `norm(M * M' - eye(size(M))) < max(AbsTol, RelTol * norm(M))`. - % By default `AbsTol = 0` and `RelTol = eps`. + % AbsTol, RelTol : :class:`numeric` + % :code:`norm(t * t' - eye(size(t))) < max(AbsTol, RelTol * norm(t))`. + % By default :code:`AbsTol = 0` and :code:`RelTol = eps`. % % Returns % ------- - % bool : logical - % true if t is isometric. + % bool : :class:`logical` + % true if :code:`t` is isometric. arguments t @@ -2271,7 +2305,7 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % input tensor. % % p : 1, 2, inf or 'fro' @@ -2300,16 +2334,16 @@ % % Arguments % --------- - % t : :class:`Tensor` + % t : :class:`.Tensor` % 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 % ------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the tensor. arguments @@ -2325,19 +2359,19 @@ % % Arguments % --------- - % v : numeric + % v : :class:`numeric` % real or complex vector containing the parameters of the tensor. % - % t : :class:`Tensor` + % t : :class:`.Tensor` % 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:`.Tensor` % output tensor, filled with the parameters. arguments @@ -2366,11 +2400,11 @@ % % Arguments % --------- - % t : Tensor + % t : :class:`Tensor` % % Returns % ------- - % a : double + % a : :class:`double` if isa(t.var, 'TrivialBlock') blocks = tensorblocks(t); diff --git a/src/tensors/charges/AbstractCharge.m b/src/tensors/charges/AbstractCharge.m index 49a0685..9f97052 100644 --- a/src/tensors/charges/AbstractCharge.m +++ b/src/tensors/charges/AbstractCharge.m @@ -1,5 +1,5 @@ classdef (Abstract) AbstractCharge - % AbstractCharge - Abstract base class for objects in a fusion category. + % Abstract base class for objects in a fusion category. %% Required categorical data. methods @@ -28,13 +28,13 @@ % % Arguments % -------- - % a : :class:`AbstractCharge` + % a : :class:`.AbstractCharge` % input charge % % Returns % ------- - % abar : :class:`AbstractCharge` - % conjugate charge suche that :code:`one(a)` is an element of :code:`a * abar` + % abar : :class:`.AbstractCharge` + % conjugate charge such that :code:`one(a)` is an element of :code:`a * abar` error('AbstractCharge:requiredMethod', ... 'Error. \nMethod must be overloaded.') end @@ -69,7 +69,7 @@ % % Returns % ------- - % c : :class:`.AbstractCharge` (1, \*) + % c : (1, :) :class:`.AbstractCharge` % the unique elements in the decomposition of the tensor product of ``a`` and % ``b`` error('AbstractCharge:requiredMethod', ... @@ -109,7 +109,7 @@ % % Returns % ------- - % F : :class:`double` (\*, \*, \*, \*) + % F : (:, :, :, :) :class:`double` % recoupling coefficients error('AbstractCharge:requiredMethod', ... 'Error. \nMethod must be overloaded.') @@ -177,7 +177,7 @@ % % Returns % ------- - % C : :class:`double` (\*, \*, \*, \*) + % C : (:, :, :, :) :class:`double` % fusion tensor error('AbstractCharge:optionalMethod', ... 'Error. \nMethod must be overloaded.') @@ -211,7 +211,7 @@ % % Returns % ------- - % R : :class:`double` (\*, \*) + % R : (:, :) :class:`double` % braiding coefficients error('AbstractCharge:optionalMethod', ... 'Error. \nMethod must be overloaded.') @@ -224,7 +224,7 @@ % Compute the fusion to splitting coefficient. % % .. todo:: - % Add diagram? + % Add diagram. % % Arguments % --------- @@ -246,7 +246,7 @@ % Compute the splitting to fusion coefficient. % % .. todo:: - % Add diagram? + % Add diagram. % % Arguments % --------- @@ -303,7 +303,7 @@ % Create a matrix-representation of an arrowflip. % % .. todo:: - % Add diagram or definition? + % Add diagram and proper definition. % % Arguments % --------- @@ -311,7 +311,7 @@ % % Returns % ------- - % F : :class:`double` (\*, \*) + % F : (:, :) :class:`double` % matrix-representation of an arrowflip F = conj(sqrt(qdim(a)) .* fusiontensor(conj(a), a, one(a))); end @@ -320,7 +320,7 @@ % Compute the full recoupling matrix from ``e`` to ``f``. % % .. todo:: - % Add proper definition? + % Add proper definition. % % Usage % ----- @@ -333,14 +333,14 @@ % charges being fused % d : :class:`.AbstractCharge` % total charges - % e : :class:`.AbstractCharge` (1, \*) + % e : (1, :) :class:`.AbstractCharge` % intermediate charges before recoupling - % f : :class:`.AbstractCharge` (1, \*) + % f : (1, :) :class:`.AbstractCharge` % intermediate charge after recoupling % % Returns % ------- - % F : :class:`double` (\*, \*, \*, \*) + % F : (:, :, :, :) :class:`double` % recoupling matrix between all allowed channels if a.fusionstyle == FusionStyle.Unique if nargin < 5, e = a * b; end @@ -414,7 +414,7 @@ % Compute the coefficient obtained by twisting a charge. % % .. todo:: - % Add diagram/definition? + % Add diagram and proper definition. % % Arguments % --------- @@ -449,19 +449,21 @@ %% Utility functions methods function [d, N] = prod(a, dim) - % Total fusion product of charges. - % - % .. todo:: - % Complete docstring + % Compute the total fusion product of array of charges along a given axis. % % Arguments % --------- - % a, b, c, ... : :class:`.AbstractCharge` + % a : :class:`.AbstractCharge` + % input array of charges + % dim : :class:`int` + % array dimension along which to take the fusion product, defaults to first + % non-trivial axis % % Returns % ------- % c : :class:`.AbstractCharge` - % total fusion product determined by subsequently multiplying input charges + % array of total fusion products determined by subsequently multiplying input + % charges along the given direction arguments a dim = find(size(a) ~= 1, 1) @@ -550,11 +552,12 @@ % Cumulative fusion product of elements. % % .. todo:: - % Complete docstring + % Complete docstring. % % Usage % ----- - % :code:`Y = cumprod(X)` computes the cumulative fusion product along the + % :code:`Y = cumprod(X)` + % computes the cumulative fusion product along the % columns of X. % % For ``FusionStyle.Unique``, ``Y`` has the same size as ``X``, which can be @@ -564,7 +567,7 @@ % % Arguments % --------- - % a: :class:`.AbstractCharge` (\*, \*) + % a: (:, :) :class:`.AbstractCharge` % % Returns % ------- @@ -663,7 +666,7 @@ % Create all combinations of vectors. % % .. todo:: - % Complete docstring + % Complete docstring. % % Usage % ----- diff --git a/src/tensors/charges/BraidingStyle.m b/src/tensors/charges/BraidingStyle.m index 5aed581..6956ee4 100644 --- a/src/tensors/charges/BraidingStyle.m +++ b/src/tensors/charges/BraidingStyle.m @@ -1,12 +1,13 @@ classdef BraidingStyle - % BraidingStyle - The braiding behaviour of charges. - % This represents the possibilities for the braiding of two charges. + % The braiding behaviour of charges. % - % Abelian - Trivial braiding with trivial twist. - % Bosonic - Symmetric braiding with trivial twist. - % Fermionic - Symmetric braiding with non-trivial twist. - % Anyonic - Arbitrary braiding and twist. - % None - No braiding defined. + % Enumeration class that encodes the possibilities for the braiding of two charges: + % + % - :code:`Abelian`: Trivial braiding with trivial twist. + % - :code:`Bosonic`: Symmetric braiding with trivial twist. + % - :code:`Fermionic`: Symmetric braiding with non-trivial twist. + % - :code:`Anyonic`: Arbitrary braiding and twist. + % - :code:`None`: No braiding defined. enumeration Abelian @@ -18,15 +19,37 @@ methods function bool = istwistless(style) + % Determine whether a given braiding style has a trivial twist. + % + % Returns :code:`true` for :code:`BraidingStyle.Abelian` and + % :code:`BraidingStyle.Bosonic` and :code:`false` for all other styles. bool = style == BraidingStyle.Abelian || style == BraidingStyle.Bosonic; end function bool = issymmetric(style) + % Determine whether a given braiding style is symmetric. + % + % Returns :code:`true` for all styles except :code:`BraidingStyle.Anyonic` and + % :code:`BraidingStyle.None`. bool = style == BraidingStyle.Abelian || style == BraidingStyle.Bosonic || ... style == BraidingStyle.Fermionic; end function c = and(a, b) + % Determine the braiding style for a direct product of charges. This effectively + % boils down to returning the least specific style. + % + % Arguments + % --------- + % style1 : :class:`.BraidingStyle` + % fusion style of first charge in direct product + % style2 : :class:`.BraidingStyle` + % fusion style of second charge in direct product + % + % Returns + % ------- + % style : :class:`.BraidingStyle` + % fusion style of direct product charge if any([a b] == BraidingStyle.None) c = BraidingStyle.None; diff --git a/src/tensors/charges/FusionStyle.m b/src/tensors/charges/FusionStyle.m index 6d7bc92..2ec3b82 100644 --- a/src/tensors/charges/FusionStyle.m +++ b/src/tensors/charges/FusionStyle.m @@ -1,10 +1,12 @@ classdef FusionStyle < uint8 - % FusionStyle - The fusion product behaviour of charges. - % This represents the possibilities for the decomposition of the fusion product of two charges. + % The fusion product behaviour of charges. % - % Unique - Single unique output. - % Simple - Multiple unique outputs. - % Generic - Multiple outputs. + % Enumeration class that encodes the possible behavior for the decomposition of the + % fusion product of two charges. + % + % - :code:`Unique`: Single unique output. + % - :code:`Simple`: Multiple unique outputs. + % - :code:`Generic`: Multiple outputs. enumeration Unique (0) @@ -14,12 +16,28 @@ methods function bool = hasmultiplicity(style) + % Determine whether a given fusionstyle admits fusion multiplicities. + % + % Returns :code:`true` for :code:`FusionStyle.Generic` and :code:`false` for all + % other styles. bool = style == FusionStyle.Generic; end function style = and(style1, style2) - % Determine the fusionstyle for a direct product of charges. This effectively + % Determine the fusion style for a direct product of charges. This effectively % boils down to returning the least specific style. + % + % Arguments + % --------- + % style1 : :class:`.FusionStyle` + % fusion style of first charge in direct product + % style2 : :class:`.FusionStyle` + % fusion style of second charge in direct product + % + % Returns + % ------- + % style : :class:`.FusionStyle` + % fusion style of direct product charge if style1 == FusionStyle.Generic || style2 == FusionStyle.Generic style = FusionStyle.Generic; diff --git a/src/tensors/charges/GtPattern.m b/src/tensors/charges/GtPattern.m index 6fd8724..537fbe5 100644 --- a/src/tensors/charges/GtPattern.m +++ b/src/tensors/charges/GtPattern.m @@ -1,5 +1,6 @@ classdef GtPattern - % Object that represents a pattern devised by Gelfand and Tsetlin. + % Object that represents a pattern devised by Gelfand and Tsetlin, used for enumerating + % :math:`\mathrm{SU}(N)` basis states. % % :: % @@ -9,18 +10,18 @@ % | m_{1,2} m_{2,2} | % \ m_{1,1} / % - % These consist of triangular arrangements of integers M_ij with the + % These consist of triangular arrangements of integers :math:`M_{ij}` with the % following property: % % .. math:: % % m_{k,l} \geq m_{k,l-1} \geq m_{k+1,l} \quad \text{for} \quad 1 <= k < l <= N % - % They will be represented using arrays of size N x N, where the elements + % They will be represented using arrays of size :math:`N \times N`, where the elements % outside of the triangular region are assumed to be zero. - properties % (Access = private) + properties M double N end @@ -115,17 +116,21 @@ % Usage % ----- % :code:`m = get(pat, k, l)` - % gets the element specified by m_kl. + % gets the element specified by :math:`M_{kl}`. + % % :code:`m = get(pat, ks, l)` - % gets a row vector of elements in the l'th row. + % gets a row vector of elements in the :code:`l`'th row. + % % :code:`m = get(pat, k, ls)` - % gets a col vector of elements in the k'th column. + % gets a column vector of elements in the :code:`k`'th column. % assert(isscalar(p)); m = p.M(k + bitshift(((l + 1 + p.N) .* (p.N - l)), -1)); end function p = set(p, k, l, val) + % Set the value of :math:`M_{kl}` to :code:`val`. + % assert(isscalar(p)); assert(checkbounds(p, k, l)); p.M(k + bitshift(((l + 1 + p.N) * (p.N - l)), -1)) = val; @@ -212,7 +217,7 @@ function disp(p) % Usage % ----- % :code:`sigma = rowsum(pat, l)` - % computes :math:`\sigma_l = \sum_{k=1}^l m_{k, l}`. + % computes :math:`\sigma_l = \sum_{k=1}^l m_{k, l}`. sigma = sum(get(p, 1:l, l)); end @@ -223,8 +228,8 @@ function disp(p) % Usage % ----- % :code:`w = pWeight(pat)` - % computes the pattern weight :math:`W(\text{pat}) = (w_1 w_2 ... w_N)` where - % :math:`w_i = \sigma_i - \sigma_{i-1}`. + % computes the pattern weight :math:`W(\text{pat}) = (w_1 w_2 ... w_N)` where + % :math:`w_i = \sigma_i - \sigma_{i-1}`. % % Note % ---- @@ -232,7 +237,7 @@ function disp(p) % % See Also % -------- - % :meth:`GtPattern.zWeight` + % :meth:`.GtPattern.zWeight` M = p.M; ctr = 0; @@ -252,12 +257,12 @@ function disp(p) % Usage % ----- % :code:`w = zWeight(pat)` - % computes the z-weight :math:`L(\text{pat}) = (l_1 l_2 ... l_N-1)` where - % :math:`l_i = \sigma_l - 1/2(\sigma_{l+1} + \sigma_{l-1})`. + % computes the z-weight :math:`L(\text{pat}) = (l_1 l_2 ... l_N-1)` where + % :math:`l_i = \sigma_l - 1/2(\sigma_{l+1} + \sigma_{l-1})`. % % Note % ---- - % This is a generalization of the m-quantum number for angular momentum. + % This is a generalization of the :math:`m`-quantum number for angular momentum. sigma = [0 arrayfun(@(l) rowsum(p, l), 1:p.N)]; w = sigma(2:end-1) - (sigma(1:end-2) + sigma(3:end))/2; diff --git a/src/tensors/charges/O2.m b/src/tensors/charges/O2.m index cd15446..9595439 100644 --- a/src/tensors/charges/O2.m +++ b/src/tensors/charges/O2.m @@ -1,16 +1,25 @@ classdef O2 < AbstractCharge - % O2 - Irreducible representations of O(2). - % This class represents the representations of O(2), also known as the - % semi-direct product of U(1) and charge conjugation. + % Irreducible representations of :math:`\mathrm{O}(2)`. % - % The representations are labeled using (j, s), indicating the behaviour - % of U(1) and charge conjugation respectively. This leads to two - % 1-dimensional representations (0, 0) and (0, 1), and for any - % non-negative j a two-dimensional representation (j, 2). + % This class represents the representations of :math:`\mathrm{O}(2)`, also known as the + % semi-direct product of :math:`\mathrm{U}(1)` and charge conjugation. + % + % The representations are labeled using :math:`(j, s)`, indicating the behaviour + % of :math:`\mathrm{U}(1)` and charge conjugation respectively. This leads to two + % 1-dimensional representations :math:`(0, 0)` and :math:`(0, 1)`, and for any + % non-negative :math:`j` a two-dimensional representation :math:`(j, 2)`. + % + % Properties + % ---------- + % j : :class:`uint8` + % :math:`\mathrm{U}(1)` label + % + % s : :class:`uint8` + % indicator for type of representation properties - j uint8 % (uint8) U1 label. - s uint8 % (uint8) indicator for type of representation. + j uint8 + s uint8 end methods diff --git a/src/tensors/charges/ProductCharge.m b/src/tensors/charges/ProductCharge.m index 5f228c7..e44c4c5 100644 --- a/src/tensors/charges/ProductCharge.m +++ b/src/tensors/charges/ProductCharge.m @@ -11,14 +11,19 @@ % % Usage % ----- - % charges = ProductCharge(charges1, charges2, ...) - % creates an (array of) charges that are representations of the direct product - % group group1 x group2 x ... + % :code:`charges = ProductCharge(charges1, charges2, ...)` creates an (array of) + % charges that are representations of the direct product group + % :math:`G_1 \otimes G_2 \otimes \dots`. % % Arguments % --------- - % charges1, charges2, ... : AbstractCharge - % charges of the separate groups. + % charges1, charges2, ... : :class:`.AbstractCharge` + % charges of the separate groups + % + % Returns + % ------- + % prodcharge : :class:`.ProductCharge` + % resulting product charge arguments (Repeating) charges @@ -36,7 +41,7 @@ end function a = cat(dim, varargin) - % Concatenate charges. + % Concatenate charges along a given axis. mask = cellfun(@isempty, varargin); firstnonempty = find(~mask, 1); if isempty(firstnonempty) @@ -96,7 +101,21 @@ end function [d, N] = prod(a, dim) - % Total fusion product of charges. + % Compute the total fusion product of array of charges along a given axis. + % + % Arguments + % --------- + % a : :class:`.ProductCharge` + % input array of charges + % dim : :class:`int` + % array dimension along which to take the fusion product, defaults to first + % non-trivial axis + % + % Returns + % ------- + % c : :class:`.ProductCharge` + % array of total fusion products determined by subsequently multiplying input + % charges along the given direction arguments a @@ -181,53 +200,53 @@ end end - function varargout = subsref(prodcharge, s) + function varargout = subsref(prodcharges, s) % Overload indexing. % % Usage % ----- - % charges_slice = charges(i1, i2, ...) - % extracts elements out of the charge array. + % :code:`charges_slice = prodcharges(i1, i2, ...)` + % extracts elements out of the charge array. % - % product_slice = charges{i} - % separate out the direct product factors. + % :code:`product_slice = prodcharges{i}` + % separates out the direct product factors. % % Arguments % --------- - % charges : ProductCharge - % array of charges. + % prodcharges : :class:`.ProductCharge` + % array of product charges % - % s : substruct - % structure containing indexing data. + % s : :class:`substruct` + % structure containing indexing data % % Returns % ------- - % charges_slice : ProductCharge - % sliced array of product charges. + % charges_slice : :class:`.ProductCharge` + % sliced array of product charges % - % product_slice : AbstractCharge - % array of factor charges. + % product_slice : :class:`.AbstractCharge` + % array of factor charges switch s(1).type case '.' - [varargout{1:nargout}] = builtin('subsref', prodcharge, s); + [varargout{1:nargout}] = builtin('subsref', prodcharges, s); case '()' - for i = 1:numel(prodcharge.charges) - prodcharge.charges{i} = prodcharge.charges{i}(s(1).subs{:}); + for i = 1:numel(prodcharges.charges) + prodcharges.charges{i} = prodcharges.charges{i}(s(1).subs{:}); end if length(s) == 1 - varargout = {prodcharge}; + varargout = {prodcharges}; return end - [varargout{1:nargout}] = subsref(prodcharge, s(2:end)); + [varargout{1:nargout}] = subsref(prodcharges, s(2:end)); case '{}' assert(length(s) == 1); assert(length(s(1).subs) == 1); assert(nargout == length(s(1).subs{1})); - varargout(1:nargout) = prodcharge.charges(s(1).subs{:}); + varargout(1:nargout) = prodcharges.charges(s(1).subs{:}); otherwise error('Undefined behaviour'); @@ -239,33 +258,36 @@ % % Usage % ----- + % % :code:`a = subsasgn(a, substruct('()', subs), b)` % % :code:`a(subs{:}) = b` - % assign array slices. + % + % Assign array slices. % % :code:`a = subsasgn(a, substruct('{}', subs), c)` % % :code:`a{i} = c` - % assign to a factor slice. + % + % Assign to a factor slice. % % Arguments % --------- - % a : :class:`ProductCharge` + % a : :class:`.ProductCharge` % array of charges to assign to. % % s : :class:`struct` % structure containing indexing data. % - % b : :class:`ProductCharge` + % b : :class:`.ProductCharge` % slice to assign. % - % c : :class:`AbstractCharge` + % c : :class:`.AbstractCharge` % factor to assign. % % Returns % ------- - % a : ProductCharge + % a : :class:`.ProductCharge` % assigned array switch s(1).type @@ -380,29 +402,9 @@ function F = Fmatrix(a, b, c, d, e, f) % Compute the full recoupling matrix from ``e`` to ``f``. % - % .. todo:: - % Add proper definition? - % - % Usage - % ----- - % :code:`F = Fmatrix(a, b, c, d, e, f)` computes the matrix between all allowed - % channels. - % - % Arguments - % --------- - % a, b, c : :class:`.AbstractCharge` - % charges being fused - % d : :class:`.AbstractCharge` - % total charges - % e : :class:`.AbstractCharge` (1, \*) - % intermediate charges before recoupling - % f : :class:`.AbstractCharge` (1, \*) - % intermediate charge after recoupling - % - % Returns - % ------- - % F : :class:`double` (\*, \*, \*, \*) - % recoupling matrix between all allowed channels + % See also + % -------- + % :meth:`.AbstractCharge.Fmatrix` if a.fusionstyle == FusionStyle.Unique if nargin < 5, e = a * b; end if nargin < 6, f = b * c; end diff --git a/src/tensors/charges/SU2.m b/src/tensors/charges/SU2.m index dd54954..5727c8d 100644 --- a/src/tensors/charges/SU2.m +++ b/src/tensors/charges/SU2.m @@ -1,10 +1,10 @@ classdef SU2 < AbstractCharge & uint8 - % SU2 - Irreducible representations of SU2. - % This class represents the representations of SU2, represented using uint8, such that - % the representative is equal to the quantum dimension. The use of uint8 limits the - % maximum to 255. The spin label can be recovered with spin = (j - 1) / 2. + % Irreducible representations of :math:`\mathrm{SU}(2)`. % - % See also AbstractCharge + % This class represents the representations of :math:`\mathrm{SU}(2)`, represented using + % :code:`uint8`, such that the representative is equal to the quantum dimension. The use + % of :math:`uint8` limits the maximum dimension to 255. The spin label can be recovered + % as :math:`s = (j - 1) / 2`. methods function style = braidingstyle(~) diff --git a/src/tensors/charges/SUN.m b/src/tensors/charges/SUN.m index 6e888ab..4fbae36 100644 --- a/src/tensors/charges/SUN.m +++ b/src/tensors/charges/SUN.m @@ -1,5 +1,13 @@ classdef SUN < AbstractCharge - % Irreducible representations of the special unitary group SU(N). + % Irreducible representations of the special unitary group :math:`\mathrm{SU}(N)`. + % + % .. todo:: + % Explain irrep labeling and give some references. + % + % Properties + % ---------- + % I : (1, :) :class:`uint8` + % integer vector representation label properties I (1,:) uint8 diff --git a/src/tensors/charges/U1.m b/src/tensors/charges/U1.m index 58e2918..e09758e 100644 --- a/src/tensors/charges/U1.m +++ b/src/tensors/charges/U1.m @@ -1,8 +1,8 @@ classdef U1 < AbstractCharge & int16 - % U1 - Irreducible representations of U(1). - % This class represents the representations of U(1), labeled using integers. + % Irreducible representations of :math:`\mathrm{U}(1)`. % - % See also AbstractCharge + % This class represents the representations of :math:`\mathrm{U}(1)`, labeled using + % integers where fusion is given by addition. methods function charge = U1(varargin) diff --git a/src/tensors/charges/Z1.m b/src/tensors/charges/Z1.m index 0629776..930cd7e 100644 --- a/src/tensors/charges/Z1.m +++ b/src/tensors/charges/Z1.m @@ -1,5 +1,5 @@ classdef Z1 < AbstractCharge - % Trivial charges. + % Trivial charge. methods function A = Asymbol(~, ~, ~) diff --git a/src/tensors/charges/Z2.m b/src/tensors/charges/Z2.m index baf5e36..2da8e96 100644 --- a/src/tensors/charges/Z2.m +++ b/src/tensors/charges/Z2.m @@ -2,8 +2,8 @@ % Irreducible representations of :math:`Z_2`. % % This class implements the trivial or sign representations of :math:`Z_2`, represented - % using {:code:`false`, :code:`true`} where multiplication is given by - % :math:`\mathrm{XOR}`, giving the multiplication table: + % using {:code:`false`, :code:`true`} where fusion is given by :math:`\mathrm{XOR}`, + % giving the multiplication table: % % .. list-table:: % @@ -17,9 +17,6 @@ % - :code:`true` % - :code:`false` % - % See Also - % -------- - % :class:`AbstractCharge` methods function A = Asymbol(a, b, c) diff --git a/src/tensors/charges/ZN.m b/src/tensors/charges/ZN.m index 88daf6d..43cbfbe 100644 --- a/src/tensors/charges/ZN.m +++ b/src/tensors/charges/ZN.m @@ -1,8 +1,14 @@ classdef ZN < AbstractCharge & uint8 - % ZN - Irreducible representations of ZN. - % This class represents representations of the cyclic group of order N. - % - % See also AbstractCharge, Z2, Z3, Z4 + % Irreducible representations of :math:`Z_N`. + % + % This class implements the representations of the cyclic group of order :math:`N`, + % represented using unteger labels where fusion is given by addition modulo + % :math:`N`. + % + % Properties + % ---------- + % N : :class:`uint8` + % integer representation label properties N (1,1) uint8 = uint8(1) diff --git a/src/tensors/charges/fSU2.m b/src/tensors/charges/fSU2.m index 3aaca94..c2398d8 100644 --- a/src/tensors/charges/fSU2.m +++ b/src/tensors/charges/fSU2.m @@ -1,7 +1,9 @@ classdef fSU2 < SU2 - % Fermionic spin charges. - % This is equivalent to representations of SU2 x fZ2, but restricted to only allow - % for the combinations of integer with trivial and halfinteger with fermion charges. + % Fermionic :math:`\mathrm{SU}(2)` charges, used to represent fermionspin. + % + % This is equivalent to representations of :math:`\mathrm{SU}(2) \otimes fZ_2`, but + % restricted to only allow for the combinations of integer with trivial and halfinteger + % with fermion charges. methods function style = braidingstyle(~) diff --git a/src/tensors/charges/fU1.m b/src/tensors/charges/fU1.m index e40fde3..fc2a9b5 100644 --- a/src/tensors/charges/fU1.m +++ b/src/tensors/charges/fU1.m @@ -1,7 +1,9 @@ classdef fU1 < U1 - % Fermionic U1 charges. - % This is equivalent to representations of U1 x fZ2, but restricted to only allow - % for the combinations of even with trivial and odd with fermion charges. + % Fermionic :math:`\mathrm{U}(1)` charges. + % + % This is equivalent to representations of :math:`\mathrm{U}(1) \otimes fZ_2`, but + % restricted to only allow for the combinations of even with trivial and odd with + % fermion charges. methods function style = braidingstyle(~) diff --git a/src/tensors/charges/fZ2.m b/src/tensors/charges/fZ2.m index 901acff..f6955b0 100644 --- a/src/tensors/charges/fZ2.m +++ b/src/tensors/charges/fZ2.m @@ -1,7 +1,5 @@ classdef fZ2 < Z2 - % Fermionic charges. - % - % See also AbstractCharge + % Fermionic charges, implemented as a graded :math:`Z_2` symmetry. methods function style = braidingstyle(~) diff --git a/src/tensors/kernels/AbelianBlock.m b/src/tensors/kernels/AbelianBlock.m index 38d3b40..ca595c7 100644 --- a/src/tensors/kernels/AbelianBlock.m +++ b/src/tensors/kernels/AbelianBlock.m @@ -1,7 +1,9 @@ classdef AbelianBlock < MatrixBlock - %ABELIANBLOCK Summary of this class goes here - % Detailed explanation goes here - + % Structure for storing symmetric tensor data for an Abelian symmetry. + % + % This represents the blocks in the block-diagonal decomposition of a tensor defined + % over graded vector spaces corresponding to an Abelian symmetry, allowing for a more + % efficient multiplication. methods function Y = axpby(a, X, b, Y, p, map) diff --git a/src/tensors/kernels/AbstractBlock.m b/src/tensors/kernels/AbstractBlock.m index ad459fb..d433725 100644 --- a/src/tensors/kernels/AbstractBlock.m +++ b/src/tensors/kernels/AbstractBlock.m @@ -1,5 +1,6 @@ classdef (Abstract) AbstractBlock % Abstract structure for storing tensor data. + % % This represents the blocks in the block-diagonal decomposition of a general tensor. %#ok<*INUSD> @@ -13,19 +14,19 @@ % % Arguments % --------- - % fun : function_handle + % fun : :class:`function_handle` % initialising function for the tensor data, with signature - % `data = fun(dims)` where dims is a row vector of dimensions. + % :code:`data = fun(dims)` where dims is a row vector of dimensions. % - % codomain : AbstractSpace + % codomain : :class:`.AbstractSpace` % vector of vector spaces that form the codomain. % - % domain : AbstractSpace + % domain : :class:`.AbstractSpace` % vector of vector spaces that form the domain. % % Returns % ------- - % X : AbstractBlock + % X : :class:`.AbstractBlock` % tensor data. if isa(codomain, 'CartesianSpace') || isa(codomain, 'ComplexSpace') || ... @@ -68,103 +69,119 @@ %% Required methods methods function Y = axpby(a, X, b, Y, p, map) - % (Abstract) Compute ```Y = permute(X, p) .* a + Y .* b```. + % Compute :code:`Y = permute(X, p) .* a + Y .* b`. % This method is the computationally critical method of this class, thus has - % special cases for scalar multiplication (a == 0), addition (nargin == 4), and - % various optimizations when a == 1, b == 0 | b == 1. Additionally, this method - % should not be called directly as it should not perform any error checks. + % special cases for scalar multiplication (:code:`a == 0`), addition + % (:code:`nargin == 4`), and various optimizations when :code:`a == 1`, + % :code:`b == 0 || b == 1`. Additionally, this method should not be called + % directly as it should not perform any error checks. % % Arguments % --------- - % a : double + % a : :class:`double` % scalar to multiply with X. % - % X : :class:`AbstractBlock` + % X : :class:`.AbstractBlock` % list of source blocks. % - % b : double + % b : :class:`double` % scalar to multiply with Y. % - % Y : :class:`AbstractBlock` + % Y : :class:`.AbstractBlock` % list of destination blocks. % - % p : int + % p : :class:`int` % permutation vector for X. % - % map : (sparse) double + % map : (sparse) :class:`double` % coefficient matrix for permuting X. % % Returns % ------- - % Y : :class:`AbstractBlock` - % Result of computing Y = permute(X, p) .* a + Y .* b. - + % Y : :class:`.AbstractBlock` + % Result of computing :code:`Y = permute(X, p) .* a + Y .* b`. + % + % Note + % ---- + % This is an abstract method that should be overloaded for each subtype. error('This method should be overloaded.'); end function [mblocks, mcharges] = matrixblocks(b) - % (Abstract) Extract a list of coupled matrix blocks. + % Extract a list of coupled matrix blocks. % % Arguments % --------- - % b : AbstractBlock + % b : :class:`.AbstractBlock` % list of input data. % % Returns % ------- - % mblocks : cell + % mblocks : :class:`cell` % list of non-zero coupled matrix blocks, sorted according to its charge. % - % mcharges : AbstractCharge + % mcharges : :class:`.AbstractCharge` % list of coupled charges. + % + % Note + % ---- + % This is an abstract method that should be overloaded for each subtype. error('This method should be overloaded.'); end function C = mul(C, A, B, a, b) - % (Abstract) Compute ```C = (A .* a) * (B .* b)```. + % Compute :code:`C = (A .* a) * (B .* b)`. % Compute the matrix product of two source tensor structures, and store the % result in the destination tensor structure. This method should not perform any % error checks. % % Arguments % --------- - % C : AbstractBlock + % C : :class:`.AbstractBlock` % location to store the result % - % A : AbstractBlock + % A : :class:`.AbstractBlock` % first matrix factor % - % B : AbstractBlock + % B : :class:`.AbstractBlock` % second matrix factor % - % a : double = 1 + % a : :class:`double` = 1 % first scalar factor % - % b : double = 1 + % b : :class:`double` = 1 % second scalar factor % % Returns % ------- - % C : AbstractBlock + % C : :class:`.AbstractBlock` % Result of computing C = (A .* a) * (B .* b) + % + % Note + % ---- + % This is an abstract method that should be overloaded for each subtype. error('This method should be overloaded.'); end function tblocks = tensorblocks(b) - % (Abstract) Extract a list of uncoupled tensor blocks. + % Extract a list of uncoupled tensor blocks. % % Arguments % --------- - % b : AbstractBlock + % b : :class:`.AbstractBlock` % list of input data. % % Returns % ------- - % tblocks : cell + % tblocks : :class:`cell` % list of non-zero uncoupled tensor blocks, sorted according to the coupled % charge and then in column-major order according to the uncoupled charges. + % + % Note + % ---- + % This is an abstract method that should be overloaded for each subtype. error('This method should be overloaded.'); end @@ -174,103 +191,106 @@ %% Optional methods methods function Y = axpy(a, X, Y, p, map) - % Compute ```Y = permute(X, p) .* a + Y```. + % Compute :code:`Y = permute(X, p) .* a + Y`. % This method is a convenience method that automatically falls back on - % ```Y = axpby(a, X, 1, Y, p, map)```, but can be overloaded if the additional + % :code:`Y = axpby(a, X, 1, Y, p, map)`, but can be overloaded if the additional % efficiency is desired. % % Arguments % --------- - % a : double + % a : :class:`double` % scalar to multiply with X. % - % X : AbstractBlock + % X : :class:`.AbstractBlock` % list of source blocks. % - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % list of destination blocks. % - % p : int + % p : :class:`int` % permutation vector for X. % - % map : (sparse) double + % map : (sparse) :class:`double` % coefficient matrix for permuting X. % % Returns % ------- - % Y : AbstractBlock - % Result of computing Y = permute(X, p) .* a + Y. + % Y : :class:`.AbstractBlock` + % Result of computing :code:`Y = permute(X, p) .* a + Y`. Y = axpby(a, X, 1, Y, p, map); end function Y = minus(X, Y) - % Subtraction of X and Y. + % Subtraction of :code:`X` and :code`Y`. % % Usage % ----- - % Y = minus(X, Y) - % Y = X - Y + % :code:`Y = minus(X, Y)` + % + % :code:`Y = X - Y` % % Arguments % --------- - % X : AbstractBlock + % X : :class:`.AbstractBlock` % first list of input data. % - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % second list of input data. % % Returns % ------- - % Y : AbstractBlock - % list of output matrices. + % Y : :class:`.AbstractBlock` + % list of output data. Y = axpby(1, X, -1, Y); end function Y = plus(X, Y) - % Addition of X and Y. + % Addition of :code:`X` and :code:`Y`. % % Usage % ----- - % Y = plus(X, Y) - % Y = X + Y + % :code:`Y = plus(X, Y)` + % + % :code:`Y = X + Y` % % Arguments % --------- - % X : AbstractBlock + % X : :class:`.AbstractBlock` % first list of input data. % - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % second list of input data. % % Returns % ------- - % Y : MatrixBlock + % Y : :class:`.AbstractBlock` % list of output data. Y = axpby(1, X, 1, Y); end function Y = times(Y, a) - % Scalar multiplication of Y and a. + % Scalar multiplication of :code:`Y` and :code:`a`. % % Usage % ----- - % Y = times(Y, a) - % Y = Y .* a + % :code:`Y = times(Y, a)` + % + % :code:`Y = Y .* a` % % Arguments % --------- - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % list of input data. % - % a : double + % a : :class:`double` % scalar factor. % % Returns % ------- - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % list of output data. Y = axpby(0, [], a, Y); @@ -281,20 +301,20 @@ % % Usage % ----- - % Y = rdivide(Y, a) - % Y = Y ./ a + % :code:`Y = rdivide(Y, a)` + % :code:`Y = Y ./ a` % % Arguments % --------- - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % list of input data. % - % a : double + % a : :class:`double` % scalar factor. % % Returns % ------- - % Y : AbstractBlock + % Y : :class:`.AbstractBlock` % list of output data. Y = axpby(0, [], 1/a, Y); @@ -305,17 +325,18 @@ % % Usage % ----- - % A = uplus(A) - % A = +A + % :code:`A = uplus(A)` + % + % :code:`A = +A` % % Arguments % --------- - % A : AbstractBlock + % A : :class:`.AbstractBlock` % list of input data. % % Returns % ------- - % A : AbstractBlock + % A : :class:`.AbstractBlock` % list of output data. end @@ -325,18 +346,19 @@ % % Usage % ----- - % A = uminus(A) - % A = -A + % :code:`A = uminus(A)` + % + % :code:`A = -A` % % Arguments % --------- - % A : MatrixBlock - % list of input matrices. + % A : :class:`.AbstractBlock` + % list of input data. % % Returns % ------- - % A : MatrixBlock - % list of output matrices. + % A : :class:`.AbstractBlock` + % list of output data. Y = Y .* (-1); end @@ -346,22 +368,44 @@ % % Arguments % --------- - % X : :class:`AbstractBlock` + % X : :class:`.AbstractBlock` % input block. % % Returns % ------- - % type : char + % type : :class:`char` % the scalar type of the data, which is one of the following: % - % - 'single' or 'double' - % - 'logical' - % - 'int8', 'int16', 'int32' or 'int64' - % - 'uint8', 'uint16', 'uint32' or 'uint64' + % - :class:`single` or :class:`double` + % - :class:`logical` + % - :class:`int8`, :class:`int16`, :class:`int32` or :class:`int64` + % - :class:`uint8`, :class:`uint16`, :class:`uint32` or :class:`uint64` error('tensors:AbstractMethod', 'This method should be overloaded.'); end + function X = ctranspose(X) + % Adjoint of a tensor. + % + % Usage + % ----- + % :code:`X = ctranspose(X)` + % + % :code:`X = X'` + % + % Arguments + % --------- + % X : :class:`.AbstractBlock` + % list of input data. + % + % Returns + % ------- + % X : :class:`.AbstractBlock` + % list of adjoint output data. + + end + + function bool = iszero(X) bool = isempty(X.var); end diff --git a/src/tensors/kernels/MatrixBlock.m b/src/tensors/kernels/MatrixBlock.m index fe70412..ef3f45b 100644 --- a/src/tensors/kernels/MatrixBlock.m +++ b/src/tensors/kernels/MatrixBlock.m @@ -1,6 +1,11 @@ classdef MatrixBlock < AbstractBlock - %MATRIXBLOCK Summary of this class goes here - % Detailed explanation goes here + % Structure for storing symmetric tensor data. + % + % This represents the blocks in the block-diagonal decomposition of a tensor defined + % over graded vector spaces. + % + % .. todo:: + % Document properties and behavior. %#ok<*INUSD> properties @@ -615,17 +620,18 @@ % % Usage % ----- - % X = ctranspose(X) - % X = X' + % :code:`X = ctranspose(X)` + % + % :code:`X = X'` % % Arguments % --------- - % X : :class:`MatrixBlock` + % X : :class:`.MatrixBlock` % list of input matrices. % % Returns % ------- - % X : :class:`MatrixBlock` + % X : :class:`.MatrixBlock` % list of adjoint output matrices. X.rank = fliplr(X.rank); diff --git a/src/tensors/kernels/TrivialBlock.m b/src/tensors/kernels/TrivialBlock.m index 76c3dcb..a3498f3 100644 --- a/src/tensors/kernels/TrivialBlock.m +++ b/src/tensors/kernels/TrivialBlock.m @@ -1,5 +1,8 @@ classdef TrivialBlock < AbstractBlock - % TrivialBlock - Data structure for tensors without symmetry. + % Data structure for tensors without symmetry. + % + % .. todo:: + % Document properties and behavior. properties var @@ -18,7 +21,7 @@ function Y = axpby(a, X, b, Y, p, ~) - %% Special case 1: scalar multiplication + %%% Special case 1: scalar multiplication if a == 0 if b == 1 return; @@ -117,25 +120,6 @@ end function Y = rdivide(Y, a) - % Scalar division of Y and a. - % - % Usage - % ----- - % Y = rdivide(Y, a) - % Y = Y ./ a - % - % Arguments - % --------- - % Y : MatrixBlock - % list of input matrices. - % - % a : double - % scalar factor. - % - % Returns - % ------- - % Y : MatrixBlock - % list of output matrices. if a == 1, return; end if a == -1, Y = -Y; return; end diff --git a/src/tensors/spaces/AbstractSpace.m b/src/tensors/spaces/AbstractSpace.m index 499b15d..6973626 100644 --- a/src/tensors/spaces/AbstractSpace.m +++ b/src/tensors/spaces/AbstractSpace.m @@ -1,9 +1,17 @@ classdef (Abstract) AbstractSpace % Abstract structure of a tensor index. + % + % Properties + % ---------- + % dimensions : :class:`int` or :class:`struct` + % Specification of the internal dimensions + % + % dual : :class:`logical` + % Flag to indicate if the space is a dual space - properties %(Access = protected) - dimensions % Specification of the internal dimensions - dual (1,1) logical = false % Flag to indicate if the space is a dual space + properties + dimensions + dual (1,1) logical = false end %% Constructors @@ -13,15 +21,15 @@ % % Repeating Arguments % ------------------- - % dimensions : int or struct + % dimensions : :class:`int` or :class:`struct` % a variable which represents the internal dimension of the space. % - % isdual : logical + % isdual : :class:`logical` % a variable which indicates if a space is dual. % % Returns % ------- - % spaces : :class:`AbstractSpace` + % spaces : :class:`.AbstractSpace` % array of spaces. arguments (Repeating) @@ -45,16 +53,20 @@ % % Repeating Arguments % ------------------- - % dimensions : int or struct + % dimensions : :class:`int` or :class:`struct` % a variable which represents the internal dimension of the space. % - % dual : logical + % dual : :class:`logical` % a variable which indicates if a space is dual. % % Returns % ------- - % spaces : :class:`AbstractSpace` + % spaces : :class:`.AbstractSpace` % array of spaces. + % + % Note + % ---- + % This abstract constructor should be overloaded for every concrete subtype. error('tensors:AbstractMethod', 'This method should be overloaded.'); end @@ -73,12 +85,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % c : (:, :) :class:`AbstractCharge` + % c : (:, :) :class:`.AbstractCharge` % list of charge combinations, where each row is a combination. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -89,12 +101,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % d : (:, :) int + % d : (:, :) :class:`int` % list of degeneracy combinations, where each row is an entry. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -105,12 +117,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % d : (1, :) numeric + % d : (1, :) :class:`double` % total dimension of each of the input spaces. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -125,12 +137,12 @@ % % Arguments % --------- - % codomain, domain : :class:`GradedSpace` + % codomain, domain : :class:`.GradedSpace` % input spaces. % % Returns % ------- - % trees : :class:`FusionTree` + % trees : :class:`.FusionTree` % list of all allowed fusion trees. rank = [length(codomain) length(domain)]; @@ -150,12 +162,12 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`AbstractSpace` + % codomain, domain : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % style : :class:`BraidingStyle` + % style : :class:`.BraidingStyle` % braiding style of the internal structure. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -166,12 +178,12 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`AbstractSpace` + % codomain, domain : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % style : :class:`FusionStyle` + % style : :class:`.FusionStyle` % fusion style of the internal structure. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -186,12 +198,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % dual spaces. for i = 1:length(spaces) @@ -205,12 +217,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input product space. % % Returns % ------- - % spaces : (1, :) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % dual product space. spaces = conj(spaces(length(spaces):-1:1)); @@ -221,12 +233,12 @@ % % Arguments % --------- - % space1, space2 : (1,1) :class:`AbstractSpace` + % space1, space2 : (1, 1) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % space : (1,1) :class:`AbstractSpace` + % space : (1, 1) :class:`.AbstractSpace` % fused space. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -237,12 +249,12 @@ % % Arguments % --------- - % space1, space2 : (1,1) :class:`AbstractSpace` + % space1, space2 : (1, 1) :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % space : (1,1) :class:`AbstractSpace` + % space : (1, 1) :class:`.AbstractSpace` % direct sum space. @@ -254,12 +266,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` - % Array of input spaces. + % spaces : (1, :) :class:`.AbstractSpace` + % array of input spaces. % % Returns % ------- - % space : (1, 1) :class:`AbstractSpace` + % space : (1, 1) :class:`.AbstractSpace` % Fused space which is isomorphic to the input product space. % TODO this is probably faster by fusing from both ends to the middle. @@ -274,12 +286,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`AbstractSpace` - % Array of input spaces. + % spaces : (1, :) :class:`.AbstractSpace` + % array of input spaces. % % Returns % ------- - % space : (1, 1) :class:`AbstractSpace` + % space : (1, 1) :class:`.AbstractSpace` % direct sum space. space = spaces(1); for i = 2:length(spaces) @@ -288,7 +300,23 @@ end function spaces = insertone(spaces, i, dual) - % insert a trivial space at position i. + % Insert a trivial space at a given position. + % + % Arguments + % --------- + % spaces : (1, :) :class:`.AbstractSpace` + % array of input spaces. + % + % i : :class:`int` + % position at which to insert trivial space, defaults to the end. + % + % dual : :class:`logical` + % indicate if trivial space should be dualized, defaults to :code:`false`. + % + % Returns + % ------- + % spaces : (1, :) :class:`.AbstractSpace` + % array of output spaces. arguments spaces i = length(spaces) + 1 @@ -307,12 +335,12 @@ % % Arguments % --------- - % spaces1, spaces2 : (1, :) :class:`AbstractSpace` + % spaces1, spaces2 : (1, :) :class:`.AbstractSpace` % input spaces, either of equal size or scalar. % % Returns % ------- - % bools : (1, :) logical + % bools : (1, :) :class:`logical` % flags that indicate if the element spaces are equal. error('tensors:AbstractMethod', 'This method should be overloaded.'); @@ -344,16 +372,16 @@ % % Usage % ----- - % bool = isequal(spaces{:}) + % :code:`bool = isequal(spaces{:})` % % Repeating Arguments % ------------------- - % spaces : (1,:) :class:`AbstractSpace` + % spaces : (1, :) :class:`.AbstractSpace` % input spaces to compare. % % Returns % ------- - % bool : (1,1) logical + % bool : (1, 1) :class:`logical` % true if all inputs are equal. arguments (Repeating) @@ -376,17 +404,17 @@ function hashable = GetMD5_helper(spaces) % Helper function for hash algorithm. This converts the space object to a data - % structure which can be processed by :func:`GetMD5`. + % structure which can be processed by :func:`.GetMD5`. % % Arguments % --------- - % spaces : :class:`AbstractSpace` + % spaces : :class:`.AbstractSpace` % input spaces. % % Returns % ------- - % hashable : cell - % data which can be accepted by :func:`GetMD5`. + % hashable : :class:`cell` + % data which can be accepted by :func:`.GetMD5`. hashable = {spaces.dimensions, spaces.dual}; end diff --git a/src/tensors/spaces/Arrow.m b/src/tensors/spaces/Arrow.m index 7159648..d867e97 100644 --- a/src/tensors/spaces/Arrow.m +++ b/src/tensors/spaces/Arrow.m @@ -1,6 +1,8 @@ classdef Arrow < logical -% Arrow - Direction of tensor leg. -% Enumeration class with directions. +% Enumeration class reprenting the possible directions of a tensor leg: +% +% - :code:`in`: Incoming tensor leg, encoded as a logical :code:`true` +% - :code:`out`: Outgoing tensor leg, encoded as a logical :code:`false` enumeration in (true) diff --git a/src/tensors/spaces/CartesianSpace.m b/src/tensors/spaces/CartesianSpace.m index 66a3f5d..eb4adc5 100644 --- a/src/tensors/spaces/CartesianSpace.m +++ b/src/tensors/spaces/CartesianSpace.m @@ -8,7 +8,7 @@ % % Repeating Arguments % ------------------- - % dimensions : (1, 1) int + % dimensions : (1, 1) :class:`int` % dimension of the vector space. % % ~ : any @@ -16,7 +16,7 @@ % % Returns % ------- - % spaces : :class:`CartesianSpace` + % spaces : :class:`.CartesianSpace` % array of cartesian spaces. arguments (Repeating) @@ -42,22 +42,24 @@ % % Usage % ----- - % spaces = CartesianSpace.new(dimensions, ~, ...) + % :code:`spaces = CartesianSpace.new(dims)` % - % spaces = CartesianSpace.new(dims) + % :code:`spaces = CartesianSpace.new(dimensions, ~, ...)` + % + % Arguments + % --------- + % dims : (1, :) :class:`int` + % vector of dimensions of all spaces. % % Repeating Arguments % ------------------- - % dimensions : struct + % dimensions : :class:`struct` % a variable which represents the internal dimension of the space. % - % dims : (1, :) int - % vector of dimensions of all spaces. - % % Returns % ------- - % spaces : :class:`CartesianSpace` - % array of spaces. + % spaces : (1, :) :class:`.CartesianSpace` + % array of cartesian vector spaces. if isstruct(varargin{1}) assert(mod(nargin, 2) == 0) @@ -89,13 +91,13 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % c : [] - % empty result. + % c : (1, :) :class:`.Z1` + % array of trivial spaces of corresponding length. c = repmat(Z1, length(spaces), 1); end @@ -105,12 +107,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % d : (1, :) int + % d : (1, :) :class:`int` % list of degeneracy combinations, with 1 element. d = [spaces.dimensions]; @@ -121,12 +123,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % d : (1, :) int + % d : (1, :) :class:`int` % total dimension of each of the input spaces. d = [spaces.dimensions]; @@ -137,13 +139,13 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`CartesianSpace` + % codomain, domain : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % style : :class:`BraidingStyle` - % Trivial braiding style + % style : :class:`.BraidingStyle` + % trivial braiding style, :code:`BraidingStyle.Abelian`. style = BraidingStyle.Abelian; end @@ -153,13 +155,13 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`CartesianSpace` + % codomain, domain : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % style : :class:`FusionStyle` - % fusion style of the internal structure. + % style : :class:`.FusionStyle` + % fusion style of the internal structure, :code:`FusionStyle.Unique`. style = FusionStyle.Unique; end @@ -187,12 +189,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % dual spaces. end @@ -201,12 +203,12 @@ % % Arguments % --------- - % space1, space2 : (1, 1) :class:`CartesianSpace` + % space1, space2 : (1, 1) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % space : (1, 1) :class:`CartesianSpace` + % space : (1, 1) :class:`.CartesianSpace` % fused space. space.dimensions = space.dimensions * space2.dimensions; @@ -217,13 +219,13 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` - % Array of input spaces. + % spaces : (1, :) :class:`.CartesianSpace` + % array of input spaces. % % Returns % ------- - % space : (1, 1) :class:`CartesianSpace` - % Fused space which is isomorphic to the input product space. + % space : (1, 1) :class:`.CartesianSpace` + % fused space which is isomorphic to the input product space. space = CartesianSpace(prod(dims(spaces)), []); end @@ -246,12 +248,12 @@ % % Arguments % --------- - % spaces1, spaces2 : (1, :) :class:`CartesianSpace` + % spaces1, spaces2 : (1, :) :class:`.CartesianSpace` % input spaces, either of equal size or scalar. % % Returns % ------- - % bools : (1, :) logical + % bools : (1, :) :class:`logical` % flags that indicate if the element spaces are equal. bools = [spaces1.dimensions] == [spaces2.dimensions]; @@ -269,17 +271,17 @@ function hashable = GetMD5_helper(spaces) % Helper function for hash algorithm. This converts the space object to a data - % structure which can be processed by :func:`GetMD5`. + % structure which can be processed by :func:`.GetMD5`. % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.CartesianSpace` % input spaces. % % Returns % ------- - % hashable : (1, :) int - % data which can be accepted by :func:`GetMD5`. + % hashable : (1, :) :class:`int` + % data which can be accepted by :func:`.GetMD5`. hashable = [spaces.dimensions]; end diff --git a/src/tensors/spaces/ComplexSpace.m b/src/tensors/spaces/ComplexSpace.m index 41afb1c..6f4a7c9 100644 --- a/src/tensors/spaces/ComplexSpace.m +++ b/src/tensors/spaces/ComplexSpace.m @@ -8,15 +8,15 @@ % % Repeating Arguments % ------------------- - % dimensions : (1, 1) int + % dimensions : (1, 1) :class:`int` % dimension of the vector space. % - % isdual : (1, 1) logical + % isdual : (1, 1) :class:`logical` % flag to denote dual spaces. % % Returns % ------- - % spaces : :class:`ComplexSpace` + % spaces : (1, :) :class:`.ComplexSpace` % array of complex spaces. arguments (Repeating) @@ -41,15 +41,15 @@ % % Repeating Arguments % ------------------- - % dimensions : int or struct + % dimensions : :class:`int` or :class:`struct` % a variable which represents the internal dimension of the space. % - % isdual : logical + % isdual : :class:`logical` % a variable which indicates if a space is dual. % % Returns % ------- - % spaces : :class:`ComplexSpace` + % spaces : :class:`.ComplexSpace` % array of spaces. arguments (Repeating) @@ -80,13 +80,13 @@ % % Arguments % --------- - % spaces : (1, :) :class:`CartesianSpace` + % spaces : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % c : [] - % empty result. + % c : (1, :) :class:`.Z1` + % array of trivial spaces of corresponding length. c = repmat(Z1, length(spaces), 1); end @@ -96,12 +96,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`ComplexSpace` + % spaces : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % d : (1, :) int + % d : (1, :) :class:`int` % list of degeneracy combinations, with 1 element. d = [spaces.dimensions]; @@ -112,12 +112,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`ComplexSpace` + % spaces : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % d : (1, :) int + % d : (1, :) :class:`int` % total dimension of each of the input spaces. d = [spaces.dimensions]; @@ -128,13 +128,13 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`ComplexSpace` + % codomain, domain : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % style : :class:`BraidingStyle` - % Trivial braiding style + % style : :class:`.BraidingStyle` + % trivial braiding style, :code:`BraidingStyle.Abelian`. style = BraidingStyle.Abelian; end @@ -144,13 +144,13 @@ % % Arguments % --------- - % codomain, domain : (1, :) :class:`ComplexSpace` + % codomain, domain : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % style : :class:`FusionStyle` - % fusion style of the internal structure. + % style : :class:`.FusionStyle` + % fusion style of the internal structure, :code:`FusionStyle.Unique`. style = FusionStyle.Unique; end @@ -168,12 +168,12 @@ % % Arguments % --------- - % space1, space2 : (1, 1) :class:`ComplexSpace` + % space1, space2 : (1, 1) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % space : (1, 1) :class:`ComplexSpace` + % space : (1, 1) :class:`.ComplexSpace` % fused space. space.dimensions = space.dimensions * space2.dimensions; @@ -185,12 +185,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`ComplexSpace` + % spaces : (1, :) :class:`.ComplexSpace` % Array of input spaces. % % Returns % ------- - % space : (1, 1) :class:`ComplexSpace` + % space : (1, 1) :class:`.ComplexSpace` % Fused space which is isomorphic to the input product space. arguments spaces @@ -227,12 +227,12 @@ % % Arguments % --------- - % spaces1, spaces2 : (1, :) :class:`ComplexSpace` + % spaces1, spaces2 : (1, :) :class:`.ComplexSpace` % input spaces, either of equal size or scalar. % % Returns % ------- - % bools : (1, :) logical + % bools : (1, :) :class:`logical` % flags that indicate if the element spaces are equal. bools = [spaces1.dimensions] == [spaces2.dimensions] & ... @@ -250,17 +250,17 @@ function hashable = GetMD5_helper(spaces) % Helper function for hash algorithm. This converts the space object to a data - % structure which can be processed by :func:`GetMD5`. + % structure which can be processed by :func:`.GetMD5`. % % Arguments % --------- - % spaces : (1, :) :class:`ComplexSpace` + % spaces : (1, :) :class:`.ComplexSpace` % input spaces. % % Returns % ------- - % hashable : (1, :) int - % data which can be accepted by :func:`GetMD5`. + % hashable : (1, :) :class:`int` + % data which can be accepted by :func:`.GetMD5`. hashable = [spaces.dimensions spaces.isdual]; end diff --git a/src/tensors/spaces/GradedSpace.m b/src/tensors/spaces/GradedSpace.m index 64d965a..358282c 100644 --- a/src/tensors/spaces/GradedSpace.m +++ b/src/tensors/spaces/GradedSpace.m @@ -8,17 +8,17 @@ % % Repeating Arguments % ------------------- - % dimensions : (1, 1) struct - % internal structure of the vector space, with fields 'charges' and - % 'degeneracies'. + % dimensions : (1, 1) :class:`struct` + % internal structure of the vector space, with fields :code:`charges` and + % :code:`degeneracies`. % - % dual : (1, 1) logical + % dual : (1, 1) :class:`logical` % flag to denote dual spaces. % % Returns % ------- - % spaces : :class:`GradedSpace` - % array of cartesian spaces. + % spaces : :class:`.GradedSpace` + % array of graded spaces. arguments (Repeating) dimensions (1, 1) struct @@ -84,28 +84,28 @@ % % Usage % ----- - % spaces = GradedSpace.new(charges, degeneracies, dual, ...) + % :code:`spaces = GradedSpace.new(charges, degeneracies, dual, ...)` % - % spaces = GradedSpace.new(dimensions, dual, ...) + % :code:`spaces = GradedSpace.new(dimensions, dual, ...)` % % Repeating Arguments % ------------------- - % dimensions : struct + % dimensions : :class:`struct` % a variable which represents the internal dimension of the space. % - % charges : :class:`AbstractCharge` + % charges : (1, :) :class:`.AbstractCharge` % charges for the internal structure of the space. % - % degeneracies : int + % degeneracies : (1, :) :class:`int` % degeneracies for the internal structure of the space. % - % dual : logical + % dual : :class:`logical` % a variable which indicates if a space is dual. % % Returns % ------- - % spaces : :class:`GradedSpace` - % array of spaces. + % spaces : :class:`.GradedSpace` + % array of graded spaces. if isstruct(varargin{1}) % default assert(mod(nargin, 2) == 0); @@ -140,13 +140,14 @@ % % Arguments % --------- - % spaces : (1, :) :class:`GradedSpace` + % spaces : (1, :) :class:`.GradedSpace` % input spaces. % % Returns % ------- - % c : (:, :) :class:`AbstractCharge` - % list of charge combinations, where each row is an entry. + % c : (:, :) :class:`.AbstractCharge` + % list of charge combinations, where each row represents a possible + % combination. if isdual(spaces(1)) c = conj(spaces(1).dimensions.charges); @@ -168,13 +169,14 @@ % % Arguments % --------- - % spaces : (1, :) :class:`GradedSpace` + % spaces : (1, :) :class:`.GradedSpace` % input spaces. % % Returns % ------- - % d : (:, :) int - % list of degeneracy combinations, where each row is an entry. + % d : (:, :) :class:`int` + % list of degeneracy combinations, where each row represents a possible + % combination. d = spaces(1).dimensions.degeneracies; for i = 2:length(spaces) @@ -187,12 +189,12 @@ % % Arguments % --------- - % spaces : (1, :) :class:`GradedSpace` + % spaces : (1, :) :class:`.GradedSpace` % input spaces. % % Returns % ------- - % d : (1, :) int + % d : (1, :) :class:`int` % total dimension of each of the input spaces. d = zeros(size(spaces)); @@ -208,12 +210,12 @@ % % Arguments % --------- - % space1, space2 : (1, 1) :class:`GradedSpace` + % space1, space2 : (1, 1) :class:`.GradedSpace` % input spaces. % % Returns % ------- - % space : (1, 1) :class:`GradedSpace` + % space : (1, 1) :class:`.GradedSpace` % fused space. space = prod([space1, space2]); @@ -224,17 +226,19 @@ % % Arguments % --------- - % spaces : (1, :) :class:`GradedSpace` - % Array of input spaces. + % spaces : (1, :) :class:`.GradedSpace` + % array of input spaces. % % Returns % ------- - % space : (1, 1) :class:`GradedSpace` - % Fused space which is isomorphic to the input product space. + % space : (1, 1) :class:`.GradedSpace` + % fused space which is isomorphic to the input product space. + arguments spaces isdual = false end + if fusionstyle(spaces) == FusionStyle.Unique c = prod(charges(spaces), 1); d = prod(degeneracies(spaces), 1); @@ -269,12 +273,12 @@ % % Arguments % --------- - % spaces1, spaces2 : (1, :) :class:`GradedSpace` + % spaces1, spaces2 : (1, :) :class:`.GradedSpace` % input spaces, either of equal size or scalar. % % Returns % ------- - % bools : (1, :) logical + % bools : (1, :) :class:`logical` % flags that indicate if the element spaces are equal. if isempty(spaces1) && isempty(spaces2) diff --git a/src/tensors/spaces/SU2Space.m b/src/tensors/spaces/SU2Space.m index 53fd3fb..55cf784 100644 --- a/src/tensors/spaces/SU2Space.m +++ b/src/tensors/spaces/SU2Space.m @@ -1,5 +1,16 @@ function V = SU2Space(charges, bonds, isdual) -% Convenience constructor for SU2-graded spaces. +% Convenience constructor for :math:`\mathrm{SU}(2)`-graded spaces. +% +% Arguments +% -------- +% charges : (1, :) :class:`int`-like +% vector of :math:`\mathrm{SU}(2)` charge labels. +% +% bonds : (1, :) :class:`int` +% degeneracy of each charge. +% +% isdual : :class:`logical` +% indicate if the space is dual. arguments charges bonds diff --git a/src/tensors/spaces/SumSpace.m b/src/tensors/spaces/SumSpace.m index 456551d..1f50ff1 100644 --- a/src/tensors/spaces/SumSpace.m +++ b/src/tensors/spaces/SumSpace.m @@ -1,10 +1,20 @@ classdef (InferiorClasses = {?GradedSpace, ?CartesianSpace, ?ComplexSpace}) SumSpace < AbstractSpace - % Direct product structure for a tensor index. + % Direct sum structure for a tensor index. %% Constructors methods function spaces = SumSpace(subspaces) - % Construct an array of vector spaces. + % Construct a direct sum of vector spaces array of vector spaces. + % + % Repeating Arguments + % ------------------- + % subspace : :class:`.AbstractSpace` + % individual subspaces of sum space. + % + % Returns + % ------- + % spaces : :class:`.SumSpace` + % array of spaces representing a direct sum of vector spaces. arguments (Repeating) subspaces @@ -16,7 +26,7 @@ dual = cell(size(subspaces)); for i = 1:length(subspaces) dual{i} = isdual(subspaces{i}(1)); - assert(all(isdual(subspaces{i}) == dual{i}), 'Direct product structure should have all dual or all regular spaces.'); + assert(all(isdual(subspaces{i}) == dual{i}), 'Direct sum structure should have all dual or all regular spaces.'); end args = [subspaces; dual]; end @@ -57,12 +67,12 @@ % % Arguments % --------- - % space1, space2 : (1,1) :class:`AbstractSpace` + % space1, space2 : (1, 1) :class:`.SumSpace` % input spaces. % % Returns % ------- - % space : (1,1) :class:`AbstractSpace` + % space : (1, 1) :class:`.SumSpace` % fused space. arguments space1 SumSpace diff --git a/src/tensors/spaces/U1Space.m b/src/tensors/spaces/U1Space.m index 48dbfb8..334d850 100644 --- a/src/tensors/spaces/U1Space.m +++ b/src/tensors/spaces/U1Space.m @@ -1,5 +1,16 @@ function V = U1Space(charges, bonds, isdual) -% Convenience constructor for U1-graded spaces. +% Convenience constructor for :math:`\mathrm{U}(1)`-graded spaces. +% +% Arguments +% -------- +% charges : (1, :) :class:`int`-like +% vector of :math:`\mathrm{U}(1)` charge labels. +% +% bonds : (1, :) :class:`int` +% degeneracy of each charge. +% +% isdual : :class:`logical` +% indicate if the space is dual. arguments charges bonds diff --git a/src/tensors/spaces/Z2Space.m b/src/tensors/spaces/Z2Space.m index 4a6feee..cb522c3 100644 --- a/src/tensors/spaces/Z2Space.m +++ b/src/tensors/spaces/Z2Space.m @@ -1,5 +1,16 @@ function V = Z2Space(charges, bonds, isdual) -% Convenience constructor for Z2-graded spaces. +% Convenience constructor for :math:`Z_2`-graded spaces. +% +% Arguments +% -------- +% charges : (1, :) :class:`logical`-like +% vector of :math:`Z_2` charge labels. +% +% bonds : (1, :) :class:`int` +% degeneracy of each charge. +% +% isdual : :class:`logical` +% indicate if the space is dual. arguments charges bonds diff --git a/src/tensors/spaces/fZ2Space.m b/src/tensors/spaces/fZ2Space.m index 0572a07..ceeb035 100644 --- a/src/tensors/spaces/fZ2Space.m +++ b/src/tensors/spaces/fZ2Space.m @@ -1,5 +1,16 @@ function V = fZ2Space(charges, bonds, isdual) -% Convenience constructor for fZ2-graded spaces. +% Convenience constructor for :math:`fZ_2`-graded spaces. +% +% Arguments +% -------- +% charges : (1, :) :class:`logical`-like +% vector of :math:`fZ_2` charge labels. +% +% bonds : (1, :) :class:`int` +% degeneracy of each charge. +% +% isdual : :class:`logical` +% indicate if the space is dual. arguments charges bonds 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..5a53f00 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 diff --git a/test/TestSolvers.m b/test/TestSolvers.m index df9fe5e..5483b9a 100644 --- a/test/TestSolvers.m +++ b/test/TestSolvers.m @@ -32,13 +32,13 @@ function linsolve(tc, spaces) [x, flag, relres] = linsolve(A, b, 'Algorithm', alg); tc.assertTrue(isapprox(norm(A * x - b) / norm(b), relres, ... 'AbsTol', tc.tol, 'RelTol', tc.tol)); - tc.assertTrue(flag == 0); + tc.assertTrue(flag == 0 || (flag == 3 && relres < tc.tol)); f = @(x) A * x; [x2, flag, relres] = linsolve(f, b, 'Algorithm', alg); tc.assertTrue(isapprox(norm(f(x2) - b) / norm(b), relres, ... 'AbsTol', tc.tol, 'RelTol', tc.tol)); - tc.assertTrue(flag == 0); + tc.assertTrue(flag == 0 || (flag == 3 && relres < tc.tol)); end end