using Pkg
Pkg.add("Turing")Getting Started
Installation
To use Turing, you need to install Julia first and then install Turing.
You will need to install Julia 1.10 or greater, which you can get from the official Julia website.
Turing is officially registered in the Julia General package registry, which means that you can install a stable version of Turing by running the following in the Julia REPL:
Supported versions and platforms
Formally, we only run continuous integration tests on: (1) the minimum supported minor version (typically an LTS release), and (2) the latest minor version of Julia. We test on Linux (x64), macOS (Apple Silicon), and Windows (x64). The Turing developer team will prioritise fixing issues on these platforms and versions.
If you run into a problem on a different version (e.g. older patch releases) or platforms (e.g. 32-bit), please do feel free to post an issue! If we are able to help, we will try to fix it, but we cannot guarantee support for untested versions.
Example usage
First, we load the Turing and StatsPlots modules. The latter is required for visualising the results.
using Turing
using StatsPlotsPrecompiling Turing... 810.5 ms ? OptimizationBase 1402.1 ms ? Optimization 2159.3 ms ? OptimizationOptimJL Info Given Turing was explicitly requested, output will be shown live WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. 5610.7 ms ? Turing 5805.4 ms ? Turing → TuringOptimExt WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. Precompiling Optimization... 822.6 ms ? OptimizationBase Info Given Optimization was explicitly requested, output will be shown live WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. 1436.4 ms ? Optimization WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. Precompiling OptimizationBase... Info Given OptimizationBase was explicitly requested, output will be shown live WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. 778.6 ms ? OptimizationBase WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: Method definition (::Type{OptimizationBase.OptimizerMissingError})(Any) in module OptimizationBase at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:23 overwritten at /home/runner/.julia/packages/OptimizationBase/sfIfa/src/solve.jl:177. ERROR: Method overwriting is not permitted during Module precompilation. Use `__precompile__(false)` to opt-out of precompilation. WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. ┌ Warning: Replacing docs for `CommonSolve.solve :: Tuple{SciMLBase.OptimizationProblem, Any, Vararg{Any}}` in module `OptimizationBase` └ @ Base.Docs docs/Docs.jl:243 WARNING: redefinition of constant OptimizationBase.OPTIMIZER_MISSING_ERROR_MESSAGE. This may fail, cause incorrect answers, or produce other errors. ┌ Warning: Replacing docs for `CommonSolve.init :: Tuple{SciMLBase.OptimizationProblem, Any, Vararg{Any}}` in module `OptimizationBase` └ @ Base.Docs docs/Docs.jl:243 ┌ Warning: Replacing docs for `CommonSolve.solve! :: Tuple{SciMLBase.AbstractOptimizationCache}` in module `OptimizationBase` └ @ Base.Docs docs/Docs.jl:243 Precompiling OptimizationOptimJL... 795.3 ms ? OptimizationBase 988.4 ms ? Optimization Info Given OptimizationOptimJL was explicitly requested, output will be shown live ┌ Warning: Module Optimization with build ID ffffffff-ffff-ffff-64ec-b57947a0275a is missing from the cache. │ This may mean Optimization [7f7a1694-90dd-40f0-9382-eb1efda571ba] does not support precompilation but is imported by a module that does. └ @ Base loading.jl:2541 1102.0 ms ? OptimizationOptimJL ┌ Warning: Module Optimization with build ID ffffffff-ffff-ffff-64ec-b57947a0275a is missing from the cache. │ This may mean Optimization [7f7a1694-90dd-40f0-9382-eb1efda571ba] does not support precompilation but is imported by a module that does. └ @ Base loading.jl:2541 Precompiling TuringOptimExt... 782.9 ms ? OptimizationBase 959.2 ms ? Optimization 1091.5 ms ? OptimizationOptimJL 3665.3 ms ? Turing Info Given TuringOptimExt was explicitly requested, output will be shown live ┌ Warning: Module Turing with build ID ffffffff-ffff-ffff-6f27-d51759e24b7a is missing from the cache. │ This may mean Turing [fce5fe82-541a-59a6-adf8-730c64b5f9a0] does not support precompilation but is imported by a module that does. └ @ Base loading.jl:2541 622.7 ms ? Turing → TuringOptimExt ┌ Warning: Module Turing with build ID ffffffff-ffff-ffff-6f27-d51759e24b7a is missing from the cache. │ This may mean Turing [fce5fe82-541a-59a6-adf8-730c64b5f9a0] does not support precompilation but is imported by a module that does. └ @ Base loading.jl:2541
We then specify our model, which is a simple Gaussian model with unknown mean and variance. Models are defined as ordinary Julia functions, prefixed with the @model macro. Each statement inside closely resembles how the model would be defined with mathematical notation. Here, both x and y are observed values, and are therefore passed as function parameters. m and s² are the parameters to be inferred.
@model function gdemo(x, y)
s² ~ InverseGamma(2, 3)
m ~ Normal(0, sqrt(s²))
x ~ Normal(m, sqrt(s²))
y ~ Normal(m, sqrt(s²))
endgdemo (generic function with 2 methods)Suppose we observe x = 1.5 and y = 2, and want to infer the mean and variance. We can pass these data as arguments to the gdemo function, and run a sampler to collect the results. Here, we collect 1000 samples using the No U-Turn Sampler (NUTS) algorithm.
chain = sample(gdemo(1.5, 2), NUTS(), 1000, progress=false)┌ Info: Found initial step size └ ϵ = 3.2
Chains MCMC chain (1000×16×1 Array{Float64, 3}):
Iterations = 501:1:1500
Number of chains = 1
Samples per chain = 1000
Wall duration = 7.0 seconds
Compute duration = 7.0 seconds
parameters = s², m
internals = n_steps, is_accept, acceptance_rate, log_density, hamiltonian_energy, hamiltonian_energy_error, max_hamiltonian_energy_error, tree_depth, numerical_error, step_size, nom_step_size, lp, logprior, loglikelihood
Use `describe(chains)` for summary statistics and quantiles.We can plot the results:
plot(chain)
and obtain summary statistics by indexing the chain:
mean(chain[:m]), mean(chain[:s²])(1.1903097080154164, 2.2291138212149995)Where to go next
NoteNote on prerequisites
Familiarity with Julia is assumed throughout the Turing documentation. If you are new to Julia, Learning Julia is a good starting point.
The underlying theory of Bayesian machine learning is not explained in detail in this documentation. A thorough introduction to the field is Pattern Recognition and Machine Learning (Bishop, 2006); an online version is available here (PDF, 18.1 MB).
The next page on Turing’s core functionality explains the basic features of the Turing language. From there, you can either look at worked examples of how different models are implemented in Turing, or specific tips and tricks that can help you get the most out of Turing.