annotate scripts/special-matrix/pascal.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 1999-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
7 ##
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
8 ## This file is part of Octave.
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
14 ##
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
19 ##
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
7016
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe]
jwe
parents: 5827
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
25
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{P} =} pascal (@var{n})
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
28 ## @deftypefnx {} {@var{P} =} pascal (@var{n}, @var{t})
20162
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
29 ## Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}.
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
30 ##
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
31 ## The default value of @var{t} is 0.
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
32 ##
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
33 ## When @code{@var{t} = 1}, return the pseudo-lower triangular
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
34 ## Cholesky@tie{}factor of the Pascal matrix (The sign of some columns may be
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
35 ## negative). This matrix is its own inverse, that is
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
36 ## @code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}.
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
37 ##
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
38 ## If @code{@var{t} = -1}, return the true Cholesky@tie{}factor with strictly
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
39 ## positive values on the diagonal.
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
40 ##
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
41 ## If @code{@var{t} = 2}, return a transposed and permuted version of
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
42 ## @code{pascal (@var{n}, 1)}, which is the cube root of the identity matrix.
2645f9ef8c88 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
43 ## That is, @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}.
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
44 ##
12639
4d777e05d47c doc: Review and update documentation for "Matrix Manipulation" chapter.
Rik <octave@nomad.inbox5.com>
parents: 12485
diff changeset
45 ## @seealso{chol}
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
46 ## @end deftypefn
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
47
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
48 function P = pascal (n, t = 0)
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
49
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27985
diff changeset
50 if (nargin < 1)
13902
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
51 print_usage ();
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
52 elseif (! (isscalar (n) && isscalar (t)))
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
53 error ("pascal: N and T must be scalars");
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
54 elseif (! any (t == [-1, 0, 1, 2]))
20711
7b608fadc663 Make error messages more specific about the variable and problem encountered.
Rik <rik@octave.org>
parents: 20162
diff changeset
55 error ("pascal: T must be -1, 0, 1, or 2, found %d", t);
11098
dcde7c5a1d29 new tests for special-matrix functions
John W. Eaton <jwe@octave.org>
parents: 10791
diff changeset
56 endif
dcde7c5a1d29 new tests for special-matrix functions
John W. Eaton <jwe@octave.org>
parents: 10791
diff changeset
57
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
58 P = zeros (n);
13894
d4404589498c pascal.m: permutation compatibility with Matlab for n=2; fixed n=0 case (Bug #34365)
Vanya Sergeev <vsergeev@gmail.com>
parents: 12639
diff changeset
59 if (n > 0)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
60 P(:,1) = 1;
13894
d4404589498c pascal.m: permutation compatibility with Matlab for n=2; fixed n=0 case (Bug #34365)
Vanya Sergeev <vsergeev@gmail.com>
parents: 12639
diff changeset
61 endif
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
62
9094
2e35cfcf6a6a fix, optimize & extend pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9051
diff changeset
63 if (t == -1)
9096
5235caf89e12 fix typo in pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9094
diff changeset
64 for j = 2:n
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
65 P(j:n,j) = cumsum (P(j-1:n-1,j-1));
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
66 endfor
9094
2e35cfcf6a6a fix, optimize & extend pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9051
diff changeset
67 else
9096
5235caf89e12 fix typo in pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9094
diff changeset
68 for j = 2:n
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
69 P(j:n,j) = -cumsum (P(j-1:n-1,j-1));
9094
2e35cfcf6a6a fix, optimize & extend pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9051
diff changeset
70 endfor
2e35cfcf6a6a fix, optimize & extend pascal
Jaroslav Hajek <highegg@gmail.com>
parents: 9051
diff changeset
71 endif
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
72
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
73 if (t == 0)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
74 P = P*P';
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
75 elseif (t == 2)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
76 P = rot90 (P, 3);
13902
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
77 if (rem (n,2) != 1)
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
78 P *= -1;
5827
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
79 endif
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
80 endif
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
81
1fe78adb91bc [project @ 2006-05-22 06:25:14 by jwe]
jwe
parents:
diff changeset
82 endfunction
11098
dcde7c5a1d29 new tests for special-matrix functions
John W. Eaton <jwe@octave.org>
parents: 10791
diff changeset
83
13902
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
84
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
85 %!assert (pascal (3,-1), [1,0,0;1,1,0;1,2,1])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
86 %!assert (pascal (3,0), [1,1,1;1,2,3;1,3,6])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
87 %!assert (pascal (3,0), pascal (3))
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
88 %!assert (pascal (3,1), [1,0,0;1,-1,0;1,-2,1])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
89 %!assert (pascal (3,2), [1,1,1;-2,-1,0;1,0,0])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
90 %!assert (pascal (0,2), [])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
91
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
92 ## Test input validation
28886
d8318c12d903 test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents: 28789
diff changeset
93 %!error <Invalid call> pascal ()
13902
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
94 %!error <N and T must be scalars> pascal ([1 2])
3af19cfc2e0f pascal.m: Update coding style. Use in-place operations where possible.
Rik <octave@nomad.inbox5.com>
parents: 13894
diff changeset
95 %!error <N and T must be scalars> pascal (1, [1 2])
20711
7b608fadc663 Make error messages more specific about the variable and problem encountered.
Rik <rik@octave.org>
parents: 20162
diff changeset
96 %!error <T must be -1> pascal (3,-2)
7b608fadc663 Make error messages more specific about the variable and problem encountered.
Rik <rik@octave.org>
parents: 20162
diff changeset
97 %!error <T must be .* or 2> pascal (3,4)