|Project Status||Documentation||Build Status|
A collection of example Stan Language programs demonstrating all methods available in Stan's cmdstan executable (as an external program) from Julia.
For most applications one of the method packages is a better choice for day to day use and for executing a Stan Language program use the most important method (sample) in StanSample.jl.
Stan.jl v7 covers all of cmdstan's methods in separate packages, i.e. StanSample.jl, StanOptimize.jl, StanVariational.jl and StanDiagnose.jl, including an option to run
generate_quantities as part of StanSample.jl.
Stan.jl v9 uses StanSample.jl v6, StanOptimize.jl v4, StanQuap.jl v4, StanDiagnose.jl v4 and StanVariational v4 and supports multithreading on C++ level. Stan.jl v9 also uses JSON.jl to generate data and init input files for cmdstan.
The StanJulia ecosystem includes 2 additional packages, StanQuap.jl (to compute MAP estimates) and DiffEqBayesStan.jl.
Stan's cmdstan executable needs to be installed separatedly. Please see cmdstan installation. If you plan to use C++ level threads, please read the
make/local-example instructions and below section and this file.
Options for multi-threading and multi-chaining
Stan.jl v9 is intended to use Stan's
cmdstan v2.28.2+ and StanSample.jl v6.
StanSample.jl v6 enables the use of c++ multithreading in the
cmdstan binary. To activate multithreading in
cmdstan this needs to be specified during the build process of
cmdstan. I typically create a
path_to_cmdstan_directory/make/local file (before running
make -j9 build) containing
STAN_THREADS=true. For an example, see the
This means StanSample supports 2 mechanisms for in parallel drawing samples for chains, i.e. on C++ level (using C++ threads) and on Julia level (by spawing a Julia process for each chain).
use_cpp_chains keyword argument for
stan_sample() determines if chains are executed on C++ level or on Julia level. By default,
By default in ether case
num_chains will be copied to either
Note: Currently I do not suggest to use both C++ level chains and Julia level chains. Based on
stan_sample() method will set either
num_cpp_chains=num_chains; num_julia_chains=1 or
num_julia_chains=num_chains;num_cpp_chain=1 (the default of
use_cpp_chains is false).
check_num_chains keyword argument in the call to
false to prevent above default behavior. See the example in the
Examples/RedCardsStudy directory for more details and an example.
Threads on C++ level can be used in multiple ways, e.g. to run separate chains and to speed up certain Stan Language operations.
StanSample.jl's SampleModel sets the C++
num_threads to 4 but for compatibility with previous versions of StanJulia this is by default (
use_cpp_chains=false) not included in the generated command line, e.g. see
sm is your SampleModel.
An example of the possible performance trade-offs between
num_julia_chains can be found in the this directory.
Conda based installation walkthrough for running Stan from Julia on Windows
Note 1: The conda way of installing also works on other platforms. See also.
Note 2: I believe if you have used CmdstanR (or CmdstanPy) to install cmdstan you can use that cmdstan version in Julia.
Make sure you have conda installed on your system and available from the command line (you can use the conda version that comes with Conda.jl or install your own).
Activate the conda environment into which you want to install cmdstan (e.g. run
conda activate stan-env from the command line) or create a new environment (
conda create --name stan-env) and then activate it.
Install cmdstan into the active conda environment by running
conda install -c conda-forge cmdstan.
You can check that cmdstan, g++, and mingw32-make are installed properly by running
conda list cmdstan, g++ --version and
mingw32-make --version, respectively, from the activated conda environment.
Start a Julia session from the conda environment in which cmdstan has been installed (this is necessary for the cmdstan installation and the tools to be found).
Add the StanSample.jl package by running ] add StanSample from the REPL.
Set the CMDSTAN environment variable so that Julia can find the cmdstan installation, e.g. from the Julia REPL do: ENV["CMDSTAN"] = "C:/Users/Jakob/.julia/conda/3/envs/stan-env/Library/bin/cmdstan" This needs to be set before you load the StanSample package by e.g. using it. You can add this line to your startup.jl file so that you don't have to run it again in every fresh Julia session.
- Updated redcradsstudy results for cmdstan-2.29.0.
- Added a README to the
- Switch to cmdstan-2.29.0
Version 9.2.0 - 9.2.2
- Switched from JSON3.jl to JSON.jl (JSON.jl supports 2D arrays)
- Switched back to by default using Julia level chains.
- Documentation improvement.
- Modified (simplified?) use of
num_chainsto define either number of chains on C++ or Julia level based on
use_cpp_chainskeyword argument to
- Use C++ multithreading features by default (4
- By default use JSON3.jl to create data.json and init.json input files.
- Support StanSanple.jl v5.3 multithreading in cmdstan
- Supports both CMDSTAN and JULIA_CMDSTAN_HOME environment variables to point to the cmdstan installation.
- Thanks to @jfb-h completed testing with using conda to install cmdstan
- Refactored code between StanBase.jl and the other StanJulia packages.
- Doc fixes by Jeremiah P S Lewis.
- Switch default output_format for read_samples() to :table.
- Add block extract for DataFrames, e.g. DataFrame(m1_1s, :log_lik)
- Doc fixes. Prepare for switching default output_format for read_samples() to :table.
This is a breaking update!
- Use KeyedArray chains as default output format returned by read_samples.
- Drop the output_format keyword argument in favor of a regulare argument.
- Removed mostly outdated cluster and thread based examples.
- Added a new package DiffEqBayesStan.jl.