diff --git a/old_link_check.py b/old_link_check.py index 3062b9f58..b6a1d87de 100644 --- a/old_link_check.py +++ b/old_link_check.py @@ -8,6 +8,15 @@ DOCS_DIR = pathlib.Path(__file__).parent / 'docs' LINK_FINDER = re.compile(r'(?:version,\s+view\s+current)|(?:link\s+rel="canonical"\s+href="(.*)"\s+/>)') + +redirected = set() +with open('redirects.txt', 'r') as f: + for line in f: + if line.startswith("#"): + continue + old, new = line.strip().split() + redirected.add(old) + links = set() def walk_html(): @@ -26,6 +35,10 @@ def find_links(): def check_links(): broken = 0 for (i, link) in enumerate(links): + raw_link = link.split('#')[0] + if raw_link in redirected: + print(f'Redirected link: {link}') + continue if i % 50 == 0: # don't spam the server time.sleep(2) diff --git a/src/cmdstan-guide/err_handling_apdx.qmd b/src/cmdstan-guide/err_handling_apdx.qmd deleted file mode 100644 index 4bfcf1cff..000000000 --- a/src/cmdstan-guide/err_handling_apdx.qmd +++ /dev/null @@ -1,27 +0,0 @@ ---- -pagetitle: Error messages and return codes ---- - -# Error messages and return codes {#err-codes} - -CmdStan executables and utility programs use streams standard output (stdout) and -standard error (stderr) to report information and error messages, respectively. - -All program executables provide a return code between 0 and 255: - - -- 0 - Program ran to termination as expected. - -- value in range [1 : 125] - Method invoked could not run due to problems with model or data. - -- value > 128 - Fatal error during execution, process terminated by signal. The signal number is retcode - 128. - - -Common sources of program error are: - -- Missing or ill-formed input data. All variables declared in the data block must be supplied in the input data file. - -- Model parameters cannot be initialized due to model misspecification. - -- Indexing errors. The Stan language provides indexing and slicing operations. Indexing errors are easy to make and difficult to debug. The compiler and runtime detect index out of bounds errors; they cannot detect the semantic errors such as indexing into the wrong variables or incorrect index updates. - diff --git a/src/cmdstan-guide/installation.qmd b/src/cmdstan-guide/installation.qmd index 371796618..047ae2e9e 100644 --- a/src/cmdstan-guide/installation.qmd +++ b/src/cmdstan-guide/installation.qmd @@ -22,10 +22,9 @@ With conda, you can install CmdStan from the [conda-forge channel](https://conda-forge.org/). This will install a pre-built version of CmdStan along with the required dependencies (i.e. a C++ compiler, a version of Make, and required -libraries) detailed below under [Source installation]. -The conda installation is designed so one can use the R or Python -bindings to CmdStan seamlessly. Additionally, it provides the command -`cmdstan_model` to activate the CmdStan makefile from anywhere. +libraries). The conda installation is designed so one can use the R or +Python bindings to CmdStan seamlessly. Additionally, it provides the +command `cmdstan_model` to activate the CmdStan makefile from anywhere. _Note_: This requires that conda has been installed already on your machine. You can either install [miniconda](https://docs.conda.io/en/latest/miniconda.html), a free, minimal installer for conda @@ -224,7 +223,7 @@ On Linux and macOS: > make examples/bernoulli/bernoulli # fit to provided data (results of 10 trials, 2 out of 10 successes) -> ./examples/bernoulli/bernoulli sample\ +> ./examples/bernoulli/bernoulli sample\ data file=examples/bernoulli/bernoulli.data.json # default output written to file `output.csv`, @@ -587,7 +586,7 @@ CmdStan v2.33.1 help 4. Build the diagnose utility bin/diagnose 5. Build all libraries and object files compile and link an executable Stan program - Note: to build using multiple cores, use the -j option to make, e.g., + Note: to build using multiple cores, use the -j option to make, e.g., for 4 cores: > make build -j4 diff --git a/src/cmdstan-guide/parallelization.qmd b/src/cmdstan-guide/parallelization.qmd index 1431a240a..7653d0d03 100644 --- a/src/cmdstan-guide/parallelization.qmd +++ b/src/cmdstan-guide/parallelization.qmd @@ -50,7 +50,7 @@ Example: ``` When the model is compiled with `STAN_THREADS` we can sample with multiple chains with a single -executable (see section [running multiple chains]{#multi-chain-sampling} for cases when this is +executable (see section [running multiple chains](mcmc_config.qmd#multi-chain-sampling) for cases when this is available). When running multiple chains `num_threads` is the maximum number of threads that can be used by all the chains combined. The exact number of threads that will be used for each chain at a given point in time is determined by the TBB scheduler. The following example start 2 chains diff --git a/src/functions-reference/deprecated_functions.qmd b/src/functions-reference/deprecated_functions.qmd index 1f9375584..34d0191b6 100644 --- a/src/functions-reference/deprecated_functions.qmd +++ b/src/functions-reference/deprecated_functions.qmd @@ -12,7 +12,7 @@ replace it. Starting in Stan 2.29, deprecated functions with drop in replacements (such as the renaming of `get_lp` or `multiply_log`) will be removed 3 versions later e.g., functions deprecated in Stan 2.20 will be removed in Stan 2.23 and placed -in [Removed Functions]. The Stan compiler can +in [Removed Functions](removed_functions.qmd). The Stan compiler can [automatically update](https://mc-stan.org/docs/stan-users-guide/using-stanc.html#stanc-pretty-printing) these on the behalf of the user for the entire deprecation window and at least one version following the removal. diff --git a/src/functions-reference/integer-valued_basic_functions.qmd b/src/functions-reference/integer-valued_basic_functions.qmd index fb55bca13..2c8976ae0 100644 --- a/src/functions-reference/integer-valued_basic_functions.qmd +++ b/src/functions-reference/integer-valued_basic_functions.qmd @@ -218,7 +218,7 @@ in the Stan Reference Manual. Return the value `x` truncated to an integer. This will throw an error if the value of `x` is too big to represent as a 32-bit signed integer. -This is similar to `trunc` (see [Rounding functions]) but the return type is of +This is similar to `trunc` (see [Rounding functions](real-valued_basic_functions.qmd#rounding-functions)) but the return type is of type `int`. For example, `to_int(3.9)` is `3`, and `to_int(-3.9)` is `-3`. {{< since 2.31 >}} diff --git a/src/reference-manual/blocks.qmd b/src/reference-manual/blocks.qmd index 8f52cb8e2..2a5c65fdb 100644 --- a/src/reference-manual/blocks.qmd +++ b/src/reference-manual/blocks.qmd @@ -171,7 +171,7 @@ applied once per chain.* `model` | yes | evaluate / leapfrog step `generated quantities` | yes | eval / sample   |   | write / sample -`\slshape (initialization)` | n/a | read, transform / chain +*`(initialization)`* | n/a | read, transform / chain **Variable Declaration Table.** @@ -271,7 +271,7 @@ generated quantities { } ``` -In this example, `y[N]` is a modeled data vector. Although it is +In this example, `y` is an array of modeled data. Although it is specified in the `data` block, and thus must have a known value before the program may be run, it is modeled as if it were generated randomly as described by the model. diff --git a/src/reference-manual/deprecations.qmd b/src/reference-manual/deprecations.qmd index 445d11abf..b09b230e4 100644 --- a/src/reference-manual/deprecations.qmd +++ b/src/reference-manual/deprecations.qmd @@ -9,7 +9,7 @@ to replace it. Starting with Stan 2.29, minor (syntax-level) deprecations can be removed 3 versions after release; e.g., syntax deprecated in Stan 2.20 will be removed in -Stan 2.23 and placed in [Removed Features]. The Stan compiler can +Stan 2.23 and placed in [Removed Features](removals.qmd). The Stan compiler can [automatically update](https://mc-stan.org/docs/stan-users-guide/using-stanc.html#stanc-pretty-printing) many of these on the behalf of the user for at least one version after they are removed. diff --git a/src/reference-manual/diagnostics.qmd b/src/reference-manual/diagnostics.qmd index 3428f6952..d3148245a 100644 --- a/src/reference-manual/diagnostics.qmd +++ b/src/reference-manual/diagnostics.qmd @@ -51,9 +51,8 @@ the reference manual chapter on transforms. The log density includes the Jacobian adjustment implied by the constraints declared on variables. The Jacobian adjustment for -constrained parameter transforms will be turned off if optimization is -used in practice, but there is as of yet no way to turn it off in -diagnostic mode. +constrained parameter transforms may be turned off for optimization, +but there is as of yet no way to turn it off in diagnostic mode. ## Configuration options diff --git a/src/reference-manual/execution.qmd b/src/reference-manual/execution.qmd index b7dcde2a4..18fafb947 100644 --- a/src/reference-manual/execution.qmd +++ b/src/reference-manual/execution.qmd @@ -57,7 +57,7 @@ displayed. ## Initialization -Initialization is the same for sampling, optimization, and diagnosis +Initialization is the same for all of Stan's algorithms. ### User-supplied initial values {-} diff --git a/src/reference-manual/expressions.qmd b/src/reference-manual/expressions.qmd index 366513bca..c953f080a 100644 --- a/src/reference-manual/expressions.qmd +++ b/src/reference-manual/expressions.qmd @@ -158,8 +158,7 @@ The following built in functions are also reserved and cannot be used as variable names: ``` -print, reject, profile, get_lp, increment_log_prob, -target +print, reject, profile, target ``` The following block identifiers are reserved and cannot be used as variable names: @@ -1117,7 +1116,11 @@ For example, this means `array[,] int` may be used where `array [,] real` or `array [,] complex` is required; as another example, `array[] real` may be used anywhere `array[] complex` is required. +Tuples have the natural extension of the above rules, applied to all +sub-types at once +8. A `tuple(U1, ..., UN)` may be promoted to a `tuple(T1, ..., TN)` if + every `Un` can be promoted to `Tn` for `n` in `1:N` #### Literals {-} diff --git a/src/reference-manual/includes.qmd b/src/reference-manual/includes.qmd index 997107ff9..c3eb1b046 100644 --- a/src/reference-manual/includes.qmd +++ b/src/reference-manual/includes.qmd @@ -83,7 +83,7 @@ contents of the included file. ## Recursive includes -Recursive includes will be ignored. For example, suppose +Recursive includes will lead to a compiler error. For example, suppose `a.stan` contains ```stan @@ -96,9 +96,20 @@ and `b.stan` contains #include a.stan ``` -The result of processing this file will be empty, because -`a.stan` will include `b.stan`, from which the include of -`a.stan` is ignored and a warning printed. +This will result in an error explaining the circular dependency: + +``` +Syntax error in './b.stan', line 1, column 0, included from +'./a.stan', line 1, column 0, included from +'./b.stan', line 1, column 0, included from +'a.stan', line 1, column 0, include error: + ------------------------------------------------- + 1: #include a.stan + ^ + ------------------------------------------------- + +File a.stan recursively included itself. +``` ## Include paths diff --git a/src/reference-manual/licenses.qmd b/src/reference-manual/licenses.qmd index 169442c1d..bce59cf91 100644 --- a/src/reference-manual/licenses.qmd +++ b/src/reference-manual/licenses.qmd @@ -61,6 +61,14 @@ SUNDIALS is distributed under the The copyright of SUNDIALS is owned by Lawrence Livermore National Security Lab. +## Threaded Building Blocks (TBB) License + +Stan uses the Threaded Building Blocks (TBB) library for parallel computations. +TBB is distributed under the + +* [Apache License, version 2](https://opensource.org/license/apache-2-0) + +The copyright of TBB is owned by Intel Corporation. ## Google test license diff --git a/src/reference-manual/statements.qmd b/src/reference-manual/statements.qmd index 958d7736a..c0c25e0b2 100644 --- a/src/reference-manual/statements.qmd +++ b/src/reference-manual/statements.qmd @@ -124,11 +124,12 @@ an expression of type `vector` may be assigned to an lvalue of type ### Lvalue summary {-} The expressions that are legal left-hand sides of assignment -statements are known as "lvalues." In Stan, there are only two +statements are known as "lvalues." In Stan, there are three kinds of legal lvalues, * a variable, or -* a variable with one or more indices. +* a variable with one or more indices, or +* a comma separated list of lvalues surrounded by `(` and `)` To be used as an lvalue, an indexed variable must have at least as many dimensions as the number of indices provided. An array of real @@ -1140,12 +1141,8 @@ message that it is already defined. ### No constraints on local variables {-} Local variables may not have constraints on their declaration. The -only types that may be used are - -``` -int, real, vector[K], row_vector[K], matrix[M, N]. -``` - +only types that may be used are listed in the [types table](types.qmd#id:constrained-types.figure) +under "local". ### Blocks within blocks {-} @@ -1430,6 +1427,10 @@ value of the log probability accumulator before and after each sampling statement, it's possible to isolate where the log probability becomes ill-defined (i.e., becomes not-a-number). +Note that print statements may not always be displayed immediately, +but rather at the end of an operation (e.g., leapfrog step). As such, +some issues such as infinite loops are difficult to debug effectively +with this technique. ## Reject statements {#reject-statements.section} diff --git a/src/reference-manual/syntax.qmd b/src/reference-manual/syntax.qmd index abcbcb3ba..be4359614 100644 --- a/src/reference-manual/syntax.qmd +++ b/src/reference-manual/syntax.qmd @@ -492,6 +492,6 @@ A second condition is that there not be more indexes provided than dimensions of the underlying expression (in general) or variable (on the left side of assignments) being indexed. A vector or row vector adds 1 to the array dimension and a matrix adds 2. That is, the type -`matrix[ , , ]`, a three-dimensional array of matrices, has five +`array[ , , ] matrix`, a three-dimensional array of matrices, has five index positions: three for the array, one for the row of the matrix and one for the column. diff --git a/src/reference-manual/types.qmd b/src/reference-manual/types.qmd index e114798b6..27c01ede6 100644 --- a/src/reference-manual/types.qmd +++ b/src/reference-manual/types.qmd @@ -83,7 +83,7 @@ size $6 \times 7$ containing values that are $3 \times 3$ matrices, and declares `z` to be a $12 \times 8 \times 15$ array of complex numbers. Prior to 2.26 Stan models used a different syntax which has since been removed. -See the [Removed Features] chapter for more details. +See the [Removed Features](removals.qmd) chapter for more details. ### Tuple types {-} @@ -167,13 +167,14 @@ Stan uses 32-bit (4-byte) integers for all of its integer representations. The maximum value that can be represented as an integer is $2^{31}-1$; the minimum value is $-(2^{31})$. -When integers overflow, their values wrap. Thus it is up to the Stan +When integers overflow, their value is determined by the underlying architecture. +On most, their values wrap, but this cannot be guaranteed. Thus it is up to the Stan programmer to make sure the integer values in their programs stay in range. In particular, every intermediate expression must have an integer value that is in range. Integer arithmetic works in the expected way for addition, -subtraction, and multiplication, but rounds the result of division +subtraction, and multiplication, but truncates the result of division (see [the Stan Functions Reference integer-valued arithmetic operators section](https://mc-stan.org/docs/functions-reference/integer-valued_basic_functions.html#int-arithmetic) for more information). @@ -398,8 +399,7 @@ real rho; Lower bounds that are negative infinity or upper bounds that are positive infinity are ignored. Stan provides constants `positive_infinity()` and `negative_infinity()` which may -be used for this purpose, or they may be read as data in the dump -format. +be used for this purpose, or they may be supplied as data. ### Affinely transformed real {-} diff --git a/src/reference-manual/user-functions.qmd b/src/reference-manual/user-functions.qmd index b9c11c62f..4282c72c1 100644 --- a/src/reference-manual/user-functions.qmd +++ b/src/reference-manual/user-functions.qmd @@ -418,6 +418,10 @@ and the recursive cases are that * a conditional statement qualifies if it has a default else clause and all of its body statements qualify. +An exception is made for "obviously infinite" loops like `while (1)`, which contain +a `return` statement and no `break` statements. The only way to exit such a loop +is to return, so they are considered as returning statements. + These rules disqualify ```stan diff --git a/src/stan-users-guide/posterior-predictive-checks.qmd b/src/stan-users-guide/posterior-predictive-checks.qmd index 82ccf5dbe..347432fd8 100644 --- a/src/stan-users-guide/posterior-predictive-checks.qmd +++ b/src/stan-users-guide/posterior-predictive-checks.qmd @@ -160,7 +160,7 @@ lower variance than the original data. That is, the model's not appropriately capturing the variance of the data. -## Posterior ``p-values'' +## Posterior ''p-values'' If a model captures the data well, summary statistics such as sample mean and standard deviation, should have similar values in @@ -176,7 +176,7 @@ $$ \cdot p\left( y^{\textrm{rep}} \mid y \right) \, \textrm{d}{y^{\textrm{rep}}}. $$ -It is important to note that``p-values'' is in quotes because these +It is important to note that ''p-values'' is in quotes because these statistics are not classically calibrated, and thus will not in general have a uniform distribution even when the model is well specified [@BayarriBerger:2000]. diff --git a/src/stan-users-guide/using-stanc.qmd b/src/stan-users-guide/using-stanc.qmd index fb5a0252f..4d87904d2 100644 --- a/src/stan-users-guide/using-stanc.qmd +++ b/src/stan-users-guide/using-stanc.qmd @@ -623,7 +623,7 @@ Warning: When a parameter is transformed in a non-linear fashion, an adjustment must be applied to account for distortion caused by the transform. This is discussed in -depth in the [Changes of variables] section. +depth in the [Changes of variables](reparameterization.qmd) section. This portion of pedantic mode tries to detect instances where such an adjustment would be necessary and remind the user. @@ -696,7 +696,7 @@ file. Invoking `stanc --auto-format ` will print a version of your model which has been re-formatted. The goal is to have this automatic formatting stay -as close as possible to the [Stan Program Style Guide]. This means spacing, +as close as possible to the [Stan Program Style Guide](style-guide.qmd). This means spacing, indentation, and line length are all regularized. _Some_ deprecated features, like the use of `#` for line comments, are replaced, but the goal is mainly to preserve the program while formatting it. @@ -810,17 +810,17 @@ The levels include these optimizations: - **O0** includes no optimizations. - **O1** includes: - - [Dead code elimination] - - [Copy propagation] - - [Constant propagation] + - [Dead code elimination](#dead-code-elimination) + - [Copy propagation](#copy-propagation) + - [Constant propagation](#constant-propagation) - **Oexperimental** includes optimizations specified by **O1** and also: - - [Automatic-differentiation level optimization] - - [One step loop unrolling] - - [Expression propagation] - - [Partial evaluation] - - [Lazy code motion] - - [Function inlining] - - [Static loop unrolling] + - [Automatic-differentiation level optimization](#automatic-differentiation-level-optimization) + - [One step loop unrolling](#one-step-loop-unrolling) + - [Expression propagation](#expression-propagation) + - [Partial evaluation](#partial-evaluation) + - [Lazy code motion](#lazy-code-motion) + - [Function inlining](#function-inlining) + - [Static loop unrolling](#static-loop-unrolling) In addition, **Oexperimental** will apply more repetitions of the optimizations, which may increase compile times. @@ -924,9 +924,9 @@ prepare_data { #### Copy propagation {-} -Copy propagation is similar to [expression propagation], but only -propagates variables rather than arbitrary expressions. This can reduce the -complexity of the code for other optimizations such as expression propagation. +Copy propagation is similar to [expression propagation](#expression-propagation), +but only propagates variables rather than arbitrary expressions. This can reduce +the complexity of the code for other optimizations such as expression propagation. Example Stan program: @@ -1048,7 +1048,7 @@ log_prob { #### One step loop unrolling {-} -One step loop unrolling is similar to [static loop unrolling]. +One step loop unrolling is similar to [static loop unrolling](#static-loop-unrolling). However, this optimization only 'unrolls' the first loop iteration, and can therefore work even when the total number of iterations is not predictable. This can speed up a program by providing more opportunities for further optimizations @@ -1103,7 +1103,7 @@ Constant propagation replaces the uses of a variable which is known to have a constant value `E` with that constant `E`. This often results in recalculating the expression, but provides more opportunities for further optimizations such as partial evaluation. Expression propagation is always -followed by [lazy code motion] to avoid unnecessarily recomputing +followed by [lazy code motion](#lazy-code-motion) to avoid unnecessarily recomputing expressions. Example Stan program: