# Release candidate of CmdStan 2.28.0

**URL:** <https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604>\
**Category:** General\
**Created:** [September 28, 2021, 8:06pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604 "2021-09-28T20:06:10Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![rok\_cesnovar](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@rok\_cesnovar](https://discourse.mc-stan.org/u/rok_cesnovar)\
**Post date:** [September 28, 2021, 8:06pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/1 "2021-09-28T20:06:10Z")

</div>

I am happy to announce that the latest release candidates of Cmdstan and Stan are now available on Github!

This release cycle brings the complex type, support for a new built-in distribution, better handling of sampling with multiple chains, more efficient algebra solver and inv\_Phi function and improve error messaging

You can find the release candidate for cmdstan [here](https://github.com/stan-dev/cmdstan/releases/tag/v2.28.0-rc2). Instructions for installing are given at the bottom of this post.

Please test the release candidate with your models and report if you experience any problems. We also kindly invite you to test the new features and provide feedback. If you feel some of the new features could be improved or should be changed before the release, please do not hesitate to comment.

The Stan development team appreciates your time and help in making Stan more efficient while maintaining a high level of reliability.

If everything goes according to plan, the 2.28 version will be released next Tuesday.

Below are some of the highlights of the new release.

## Complex type

Stan now supports complex numbers with all of the standard complex functions, including natural logarithm `log(z)`, natural exponentiation `exp(z)`, and powers `pow(z1, z2)`, as well as all of the trig and hyperbolic trigonometric functions and their inverse, such as `sin(z)`, `acos(z)`, `tanh(z)` and `asinh(z)`.

More detailed documentation that will be part of the User’s guide is currently available [here](https://github.com/stan-dev/docs/blob/a0b6d705eed789b77918b190398cee4856f044a5/src/stan-users-guide/complex-numbers.Rmd). The function reference is available [here](https://github.com/stan-dev/docs/blob/a0b6d705eed789b77918b190398cee4856f044a5/src/functions-reference/complex-valued_basic_functions.Rmd).

## Skew double exponential distribution

All typical distributions-related functions are now available for the Skew double exponential distribution:

`skew_double_exponential_lpdf`, `skew_double_exponential_cdf`, `skew_double_exponential_lcdf`, `skew_double_exponential_lccdf` and `skew_double_exponential_rng`.

The functions reference is available [here](https://mc-stan.org/docs/2_27/functions-reference/skew-double-exponential-distribution.html).

## More efficient multi chain sampling with cmdstan using threads in a single executable

It is now possible to sample using NUTS with multiple chains with a single executable with multiple chains running using threads. This should be slightly faster in general and also reduces the memory footprint as all chains share the same copy of data, while previously each chain had its own copy of all the input data.

When using within-chain parallelization all chains started within a single executable can share all the available threads. This means what once a chain finishes the threads will be reused in the other chains. This type of resource sharing was previously unavailable.

More details are currently available [here](https://github.com/stan-dev/docs/blob/e2b3626405775b711ced6db7a76f508a8c2503ac/src/cmdstan-guide/mcmc_sampling_intro.Rmd#L92).

## New `num_threads` command-line argument

The number of threads used with within-chain parallelization can now be specified as a regular argument to the CmdStan executable.

Previously the number of threads was specifed via an environment variable STAN\_NUM\_THREADS.

Details are available [here](https://github.com/stan-dev/docs/blob/e2b3626405775b711ced6db7a76f508a8c2503ac/src/cmdstan-guide/parallelization.Rmd#L33).

## More efficient Power & Newton algebra solvers and the inv\_Phi function

The autodifferentiation in the Powell and Newton solvers now efficiently computes cotangents by replacing matrix inversion with a smaller number of matrix solves.

The inv\_Phi should be approximately 2x faster with precision of 16 digits with changes based on the Fortran algorithm described in Wichura, M. J. (1988) Algorithm AS 241: The percentage points of the normal distribution. Applied Statistics, 37, 477–484.

## Automatic handling of precompiled headers on Windows with RTools 4.0

With CmdStan 2.28, precompiled headers that speedup model compilation are enabled by default on Windows when using RTools 4.0. Previously, they were only enabled if the user manually specified `PRECOMPILED_HEADERS=true` in the make/local file.

## Improved error messaging/type error explanations in stanc3

The Stan-to-C++ compiler now has an improved error messaging, particulary with better explanations in case of type mismatches.

## How to install?

Download the tar.gz file from the link above, extract it and use it the way you use any Cmdstan release. We also have an online Cmdstan guide available at [CmdStan User’s Guide](https://mc-stan.org/docs/2_27/cmdstan-guide/)

If you are using cmdstanpy, make sure you point to the folder where you extracted the tar.gz file with

```no-highlight

set_cmdstan_path(os.path.join('path','to','cmdstan'))

```

With CmdStanR you can install the release candidate using

```r

cmdstanr::install_cmdstan(version = "2.28.0-rc2", cores = 4)

```

And then select the RC with

```r

cmdstanr::set_cmdstan_path(file.path(Sys.getenv("HOME"), ".cmdstanr", "cmdstan-2.28.0-rc2"))

```

---

<div class="post-metadata">

**Author:** ![mike-lawrence](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mike-lawrence/32/59_2.png) [@mike-lawrence](https://discourse.mc-stan.org/u/mike-lawrence)\
**Post date:** [September 28, 2021, 8:14pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/2 "2021-09-28T20:14:01Z")

</div>

> [@rok\_cesnovar](#):
>
> When using within-chain parallelization all chains started within a single executable can share all the available threads. This means what once a chain finish the threads will be used in the other chains. This type of resource sharing was previously unavailable.

Whoa! Amazing feature!

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [September 30, 2021, 1:50am UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/3 "2021-09-30T01:50:02Z")

</div>

CmdStanPy has some tests for ADVI, and results for one model are very different between the reference CSV file from 2.20 and outputs from 2.28 rc2:

the model is taken from the test models in the Stan repo - [stan/eta\_should\_be\_big.stan at develop · stan-dev/stan · GitHub](https://github.com/stan-dev/stan/blob/develop/src/test/test-models/good/variational/eta_should_be_big.stan)

Stan 2.20 CSV file estimates are (added spaces for readibility):

```
lp __, log_p__ , log_g__, mu.1, mu.2
# Stepsize adaptation complete.
# eta = 1
0, 0, 0, 31.0299, 28.8141

```

which may or may not have been as expected, since eta=1 - is that big?

Stan 2.28-rc2 CSV file outputs are:

```
lp __, log_p__ , log_g__, mu.1, mu.2
# Stepsize adaptation complete.
# eta = 100
0, 0, 0, 7261.34, 3725.82

```

this time, `eta=100` and the estimates are very different.  
not sure what this means, other than that the tests on CmdStanPy I/O are extremely brittle.

do we have regression tests for ADVI, or is it considered experimental?  
are there changes to ADVI in 2.28?

---

<div class="post-metadata">

**Author:** ![rok\_cesnovar](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@rok\_cesnovar](https://discourse.mc-stan.org/u/rok_cesnovar)\
**Post date:** [September 30, 2021, 6:51am UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/4 "2021-09-30T06:51:36Z")

</div>

> [@mitzimorris](#):
>
> do we have regression tests for ADVI, or is it considered experimental?

The tests for ADVI are here: [https://github.com/stan-dev/stan/tree/develop/src/test/unit/variational](https://github.com/stan-dev/stan/tree/develop/src/test/unit/variational)  
A test that uses exactly the model you mention is here: [https://github.com/stan-dev/stan/blob/develop/src/test/unit/variational/eta\_adapt\_big\_test.cpp](https://github.com/stan-dev/stan/blob/develop/src/test/unit/variational/eta_adapt_big_test.cpp)

The EXPECT value at the bottom would suggest the correct value is 100.0? But my confidence here is very low as my understanding of all the ADVI stuff is very basic.

> [@mitzimorris](#):
>
> are there changes to ADVI in 2.28?

The last meaningful changed (non-docs or formatting) in the ADVI files were done in May 2019 so before 2.20.

---

<div class="post-metadata">

**Author:** ![wds15](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/wds15/32/908_2.png) [@wds15](https://discourse.mc-stan.org/u/wds15)\
**Post date:** [September 30, 2021, 11:04am UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/5 "2021-09-30T11:04:30Z")

</div>

What does `diagnose` tell you about the gradients?

---

<div class="post-metadata">

**Author:** ![rok\_cesnovar](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@rok\_cesnovar](https://discourse.mc-stan.org/u/rok_cesnovar)\
**Post date:** [September 30, 2021, 11:59am UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/6 "2021-09-30T11:59:50Z")

</div>

Diagnose looks good on my end:

```
TEST GRADIENT MODE

 Log probability=-190015

 param idx value model finite diff error
         0 -1.59078 7.00048 7.00049 -1.26242e-05
         1 -0.705393 5.00021 5.0002 1.34744e-05

```

Its similar with 2.27.0.

---

<div class="post-metadata">

**Author:** ![spinkney](https://avatars.discourse-cdn.com/v4/letter/s/dec6dc/32.png) [@spinkney](https://discourse.mc-stan.org/u/spinkney)\
**Post date:** [October 1, 2021, 10:24am UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/7 "2021-10-01T10:24:23Z")

</div>

`inv_Phi` is looking good: here’s profiling between 2.28.0rc2 and 2.27

```r
name thread_id total_time forward_time reverse_time chain_stack no_chain_stack autodiff_calls no_autodiff_calls
1 inv_Phi_2.28 0x10fec5e00 1.75221 1.23417 0.518044 38528000 0 385281 1
1 inv_Phi_2.27 0x116b41e00 5.0122 4.27536 0.736845 48473000 0 484731 1

```

on the stan model with N = 1000

```stan
data {
 int N;
}
parameters {
  vector<lower=0, upper=1>[N] x;
}
model {
  vector[N] y; 
  profile("inv_Phi") {
   y = inv_Phi(x); 
  }
}

```

---

<div class="post-metadata">

**Author:** ![JLC](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/jlc/32/12520_2.png) [@JLC](https://discourse.mc-stan.org/u/JLC)\
**Post date:** [October 1, 2021, 7:13pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/8 "2021-10-01T19:13:40Z")

</div>

I’m getting an error when trying to compile from github:

```
In file included from src/cmdstan/main.cpp:1:
src/cmdstan/command.hpp:27:10: fatal error: stan/callbacks/unique_stream_writer.hpp: No such file or directory
   27 | #include <stan/callbacks/unique_stream_writer.hpp>
      | ^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
compilation terminated.

```

Do I need to pull unique\_stream\_writer.hpp from elsewhere?

---

<div class="post-metadata">

**Author:** ![rok\_cesnovar](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@rok\_cesnovar](https://discourse.mc-stan.org/u/rok_cesnovar)\
**Post date:** [October 1, 2021, 7:28pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/9 "2021-10-01T19:28:30Z")

</div>

Did you do a fresh git clone of cmdstan? Did you clone recursively?

---

<div class="post-metadata">

**Author:** ![stevebronder](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/stevebronder/32/17242_2.png) [@stevebronder](https://discourse.mc-stan.org/u/stevebronder)\
**Post date:** [October 1, 2021, 7:31pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/10 "2021-10-01T19:31:49Z")

</div>

If you are using the cmdstan repo that’s most likely because your stan repo was not updated

---

<div class="post-metadata">

**Author:** ![JLC](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/jlc/32/12520_2.png) [@JLC](https://discourse.mc-stan.org/u/JLC)\
**Post date:** [October 1, 2021, 7:57pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/11 "2021-10-01T19:57:22Z")

</div>

A fresh git clone solved the issue. But, the build tag is still:  
`--- CmdStan v2.27.0 built ---`

---

<div class="post-metadata">

**Author:** ![rok\_cesnovar](https://avatars.discourse-cdn.com/v4/letter/r/7bcc69/32.png) [@rok\_cesnovar](https://discourse.mc-stan.org/u/rok_cesnovar)\
**Post date:** [October 1, 2021, 8:23pm UTC](https://discourse.mc-stan.org/t/release-candidate-of-cmdstan-2-28-0/24604/12 "2021-10-01T20:23:42Z")

</div>

That will be updated once the official release is made.