# Julia Interface % NB: If you are reading this file in docs/languages, you are reading a generated output! % This should be apparent due to the html tags everywhere. % If you are reading this in julia/docs/src, you are reading the true source! % Please only make edits in the later file, since the first is DELETED each re-build. --- ## Installation ### From Source This section assumes you have followed the [Getting Started guide](../getting-started.rst) to install TinyStan's pre-requisites and downloaded a copy of the TinyStan source code. To install the Julia interface, you can either install it directly from Github by running the following inside a Julia REPL ```julia ] add https://github.com/WardBrian/tinystan.git:clients/julia ``` Or, since you have already downloaded the repository, you can run ```julia ] dev clients/julia/ ``` from the TinyStan folder. The first time you compile a model, the TinyStan source code for your current version will be downloaded to a hidden directory in the users `HOME` directory. To use the TinyStan source you've manually downloaded instead of one the package will download for you, you must use [`set_tinystan_path()`](TinyStan.set_tinystan_path!) or the `$TINYSTAN` environment variable. Note that the Julia package depends on Julia 1.6+ and the `Inflate` package. ## Example Program An example program is provided alongside the Julia interface code in `example.jl`:

Show example.jl

```{literalinclude} ../../clients/julia/example.jl :language: julia ```

## API Reference ### Model interface # **`TinyStan.Model`** — *Type*. ```julia Model(model::String; stanc_args::Vector{String} = String[], make_args::Vector{String} = String[], warn::Bool = true) ``` Load a Stan model for inference, compiling it if necessary. If model is a path to a file ending in `.stan`, this will first compile the model. Compilation occurs if no shared object file exists for the supplied Stan file or if a shared object file exists and the Stan file has changed since last compilation. This is equivalent to calling [`compile_model`](julia.md#TinyStan.compile_model) and then the constructor. If `warn` is false, the warning about re-loading the same shared objects is suppressed. source
# **`TinyStan.sample`** — *Function*. ```julia sample(model::Model, data::String=""; num_chains::Int=4, inits::Union{nothing,AbstractString,AbstractArray{AbstractString}}=nothing, seed::Union{Nothing,UInt32}=nothing, id::Int=1, init_radius=2.0, num_warmup::Int=1000, num_samples::Int=1000, metric::HMCMetric=DIAGONAL, init_inv_metric::Union{Nothing,Array{Float64}}=nothing, save_metric::Bool=false, adapt::Bool=true, delta::Float64=0.8, gamma::Float64=0.05, kappa::Float64=0.75, t0::Int=10, init_buffer::Int=75, term_buffer::Int=50, window::Int=25, save_warmup::Bool=false, stepsize::Float64=1.0, stepsize_jitter::Float64=0.0, max_depth::Int=10, refresh::Int=0, num_threads::Int=-1) ``` Run Stan's No-U-Turn Sampler (NUTS) to sample from the posterior. An in-depth explanation of the parameters can be found in the [Stan documentation](https://mc-stan.org/docs/reference-manual/mcmc.html). Returns a tuple of the parameter names, the draws, and the metric if `save_metric` is true. source
# **`TinyStan.HMCMetric`** — *Type*. Choices for the structure of the mass matrix used in the HMC sampler. Either `UNIT`, `DENSE`, or `DIAGONAL`. source
# **`TinyStan.pathfinder`** — *Function*. ```julia pathfinder(model::Model, data::String=""; num_paths::Int=4, inits::Union{nothing,AbstractString,AbstractArray{AbstractString}}=nothing, seed::Union{Nothing,UInt32}=nothing, id::Int=1, init_radius=2.0, num_draws::Int=1000, max_history_size::Int=5, init_alpha::Float64=0.001, tol_obj::Float64=1e-12, tol_rel_obj::Float64=1e4, tol_grad::Float64=1e-8, tol_rel_grad::Float64=1e7, tol_param::Float64=1e-8, num_iterations::Int=1000, num_elbo_draws::Int=25, num_multi_draws::Int=1000, calculate_lp::Bool=true, psis_resample::Bool=true, refresh::Int=0, num_threads::Int=-1) ``` Run the Pathfinder algorithm to approximate the posterior. See [Stan's documentation](https://mc-stan.org/docs/reference-manual/pathfinder.html) for more information on the algorithm. Returns a tuple of the parameter names and the draws. source
# **`TinyStan.optimize`** — *Function*. ```julia optimize(model::Model, data::String=""; init::Union{Nothing,AbstractString}=nothing, seed::Union{UInt32,Nothing}=nothing, id::Int=1, init_radius::Float64=2.0, algorithm::OptimizationAlgorithm=LBFGS, jacobian::Bool=false, num_iterations::Int=2000, max_history_size::Int=5, init_alpha::Float64=0.001, tol_obj::Float64=1e-12, tol_rel_obj::Float64=1e4, tol_grad::Float64=1e-8, tol_rel_grad::Float64=1e7, tol_param::Float64=1e-8, refresh::Int=0, num_threads::Int=-1) ``` Optimize the model parameters using the specified algorithm. This will find either the maximum a posteriori (MAP) estimate or the maximum likelihood estimate (MLE) of the model parameters, depending on the value of the `jacobian` parameter. Additional parameters can be found in the [Stan documentation](https://mc-stan.org/docs/reference-manual/optimization.html). Returns a tuple of the parameter names and the optimized values. source
# **`TinyStan.OptimizationAlgorithm`** — *Type*. Choices for the optimization algorithm to use. Either `NEWTON`, `BFGS`, or `LBFGS`. source
# **`TinyStan.laplace_sample`** — *Function*. ```julia laplace_sample(model::Model, mode::Union{AbstractString,Array{Float64}}, data::AbstractString=""; num_draws::Int=1000, jacobian::Bool=true, calculate_lp::Bool=true, save_hessian::Bool=false, seed::Union{UInt32,Nothing}=nothing, refresh::Int=0, num_threads::Int=-1) ``` Sample from the Laplace approximation of the posterior centered at the provided mode. The mode can be either a JSON string or an array of floats, often obtained from the [`optimize`](julia.md#TinyStan.optimize) function. Returns a tuple of the parameter names and the draws. source
### Compilation utilities # **`TinyStan.compile_model`** — *Function*. ```julia compile_model(stan_file; stanc_args=[], make_args=[]) ``` Run TinyStan’s Makefile on a `.stan` file, creating the `.so` used by StanModel and return a path to the compiled library. Arguments to `stanc3` can be passed as a vector, for example `["--O1"]` enables level 1 compiler optimizations. Additional arguments to `make` can be passed as a vector, for example `["STAN_THREADS=true"]` enables the model's threading capabilities. If the same flags are defined in `make/local`, the versions passed here will take precedent. This function checks that the path to TinyStan is valid and will error if it is not. This can be set with [`set_tinystan_path!()`](julia.md#TinyStan.set_tinystan_path!). source
# **`TinyStan.get_tinystan_path`** — *Function*. ```julia get_tinystan_path() -> String ``` Return the path the the TinyStan directory. If the environment variable `TINYSTAN` is set, this will be returned. Otherwise, this function downloads a matching version of TinyStan under a folder called `.tinystan` in the user's home directory. See [`set_tinystan_path!()`](julia.md#TinyStan.set_tinystan_path!) to set the path from within Julia. source
# **`TinyStan.set_tinystan_path!`** — *Function*. ```julia set_tinystan_path!(path) ``` Set the path TinyStan. source