diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 34128d29..13e3bb8c 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -31,10 +31,10 @@ jobs: with: submodules: recursive - - name: Set up Python 3.9 + - name: Set up Python 3.11 uses: actions/setup-python@v5 with: - python-version: 3.9 + python-version: 3.11 - name: Install dependencies (python) run: | diff --git a/R/DESCRIPTION b/R/DESCRIPTION index d3876ae4..f3567f82 100644 --- a/R/DESCRIPTION +++ b/R/DESCRIPTION @@ -8,7 +8,7 @@ Description: BridgeStan provides efficient in-memory access to the methods of a including log densities, gradients, Hessians, and constraining and unconstraining transforms. Encoding: UTF-8 -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 Roxygen: list(markdown = TRUE, r6 = TRUE) Suggests: testthat (>= 3.0.0), diff --git a/R/R/bridgestan.R b/R/R/bridgestan.R index ceb0bc93..0ab74bf8 100755 --- a/R/R/bridgestan.R +++ b/R/R/bridgestan.R @@ -223,7 +223,7 @@ StanModel <- R6::R6Class("StanModel", #' @description #' This accepts a JSON string of constrained parameters and returns the unconstrained parameters. #' - #' The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). + #' The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). #' @param json Character vector containing a string representation of JSON data. #' @return The unconstrained parameters of the model. param_unconstrain_json = function(json) { diff --git a/R/man/StanModel.Rd b/R/man/StanModel.Rd index 8dedc776..92533067 100644 --- a/R/man/StanModel.Rd +++ b/R/man/StanModel.Rd @@ -269,7 +269,7 @@ The unconstrained parameters of the model. \subsection{Method \code{param_unconstrain_json()}}{ This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the \href{https://mc-stan.org/docs/cmdstan-guide/json.html}{JSON Format for CmdStan}. +The JSON is expected to be in the \href{https://mc-stan.org/docs/cmdstan-guide/json_apdx.html}{JSON Format for CmdStan}. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{StanModel$param_unconstrain_json(json)}\if{html}{\out{
}} } diff --git a/docs/conf.py b/docs/conf.py index eebed446..27a7f535 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ import bridgestan -most_recent_release = 'v' + bridgestan.__version__ +most_recent_release = "v" + bridgestan.__version__ version = os.getenv("BS_DOCS_VERSION", most_recent_release) if version == "latest": # don't display a version number for "latest" docs @@ -45,17 +45,13 @@ "myst_parser", ] -myst_enable_extensions = [ - "substitution" -] -myst_substitutions = { - "most_recent_release": most_recent_release -} +myst_enable_extensions = ["substitution"] +myst_substitutions = {"most_recent_release": most_recent_release} -suppress_warnings = ["myst.xref_missing"] # Julia doc generates raw html links +suppress_warnings = ["myst.xref_missing"] # Julia doc generates raw html links templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md", "languages/_*"] # -- Options for HTML output ------------------------------------------------- @@ -131,7 +127,7 @@ autoclass_content = "both" -# Julia and C++ doc build +# Other languages doc build import os import subprocess import pathlib @@ -161,7 +157,7 @@ ) # delete some broken links in the generated R docs - StanModel = (pathlib.Path(__file__).parent / "languages" / "_r" / "StanModel.md") + StanModel = pathlib.Path(__file__).parent / "languages" / "_r" / "StanModel.md" text = StanModel.read_text() start = text.find("### Public methods") end = text.find("### Method `") @@ -169,7 +165,7 @@ StanModel.write_text(text) # replaces the headers with more appropriate levels for embedding - for f in (pathlib.Path(__file__).parent / "languages" / "_r" ).iterdir(): + for f in (pathlib.Path(__file__).parent / "languages" / "_r").iterdir(): text = f.read_text() text = re.sub(r"(#+) ", r"##\1 ", text) f.write_text(text) @@ -195,3 +191,23 @@ exclude_patterns += ["languages/c-api.rst"] else: extensions.append("breathe") + + +try: + print("Checking Rust doc availability") + subprocess.run(["cargo", "--version"], check=True, capture_output=True) +except Exception as e: + if RUNNING_IN_CI: + raise e + else: + print("Rust not installed, skipping Rust Doc") + exclude_patterns += ["languages/rust.md", "languages/_rust"] +else: + extensions.append("sphinxcontrib_rust") + myst_enable_extensions += ["colon_fence", "attrs_block"] + rust_crates = { + "bridgestan": str(pathlib.Path(__file__).parent.parent / "rust"), + } + rust_doc_dir = "languages/_rust" + rust_rustdoc_fmt = "md" + rust_generate_mode = "changed" if not RUNNING_IN_CI else "always" diff --git a/docs/languages/_r/StanModel.md b/docs/languages/_r/StanModel.md index f54e5a85..41d8534d 100644 --- a/docs/languages/_r/StanModel.md +++ b/docs/languages/_r/StanModel.md @@ -314,7 +314,7 @@ The unconstrained parameters of the model. This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). ###### Usage diff --git a/docs/languages/_rust/bridgestan/lib.md b/docs/languages/_rust/bridgestan/lib.md new file mode 100644 index 00000000..cf6dfee6 --- /dev/null +++ b/docs/languages/_rust/bridgestan/lib.md @@ -0,0 +1,687 @@ +# Crate `bridgestan` + +:::::::{rust:crate} bridgestan +:index: 0 + + ::: + ::: +:::{rust:use} bridgestan +:used_name: self + +::: +:::{rust:use} bridgestan +:used_name: crate + +::: +:::{rust:use} bridgestan::BridgeStanError +:used_name: BridgeStanError + +::: +:::{rust:use} bridgestan::Model +:used_name: Model + +::: +:::{rust:use} bridgestan::Rng +:used_name: Rng + +::: +:::{rust:use} bridgestan::StanLibrary +:used_name: StanLibrary + +::: +:::{rust:use} bridgestan::compile_model +:used_name: compile_model + +::: +:::{rust:use} bridgestan::download_bridgestan_src +:used_name: download_bridgestan_src + +::: +:::{rust:use} bridgestan::open_library +:used_name: open_library + +::: + +:::{rubric} Variables +::: + +::::::{rust:variable} bridgestan::VERSION +:index: 0 +:vis: pub +:toc: const VERSION +:layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"VERSION"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"}] + + ::: + ::: +:::::: + +:::{rubric} Functions +::: + +::::::{rust:function} bridgestan::compile_model +:index: 0 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"compile_model"},{"type":"punctuation","value":"("},{"type":"name","value":"bs_path"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Path","target":"Path"},{"type":"punctuation","value":", "},{"type":"name","value":"stan_file"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Path","target":"Path"},{"type":"punctuation","value":", "},{"type":"name","value":"stanc_args"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"make_args"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"PathBuf","target":"PathBuf"},{"type":"punctuation","value":">"}] + + ::: + Compile a Stan Model. Requires a path to the BridgeStan sources (can be + downloaded with [`download_bridgestan_src`](crate::download_bridgestan_src) + if that feature is enabled), a path to the `.stan` file, and + additional arguments for the Stan compiler and the `make` command. + + + ::: +:::::: +::::::{rust:function} bridgestan::download_bridgestan_src +:index: 0 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"download_bridgestan_src"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"PathBuf","target":"PathBuf"},{"type":"punctuation","value":">"}] + + ::: + Download and unzip the BridgeStan source distribution for this version + to `~/.bridgestan/bridgestan-$VERSION`. + Requires feature `download-bridgestan-src`. + + + ::: +:::::: +::::::{rust:function} bridgestan::open_library +:index: 0 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"open_library"},{"type":"punctuation","value":"<"},{"type":"name","value":"P"},{"type":"punctuation","value":": "},{"type":"link","value":"AsRef","target":"AsRef"},{"type":"punctuation","value":"<"},{"type":"link","value":"OsStr","target":"OsStr"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":"("},{"type":"name","value":"path"},{"type":"punctuation","value":": "},{"type":"link","value":"P","target":"P"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"}] + + ::: + Open a compiled Stan library. + + The library should have been compiled with BridgeStan, + with the same version as the Rust library. + + + ::: +:::::: + +:::{rubric} Enums +::: + +::::::{rust:enum} bridgestan::BridgeStanError +:index: 1 +:vis: pub +:layout: [{"type":"keyword","value":"enum"},{"type":"space"},{"type":"name","value":"BridgeStanError"}] + + ::: + Error type for bridgestan interface + + + ::: +:::::{rust:struct} bridgestan::BridgeStanError::InvalidLibrary +:index: 2 +:vis: pub +:toc: InvalidLibrary +:layout: [{"type":"name","value":"InvalidLibrary"},{"type":"punctuation","value":"("},{"type":"link","value":"LoadingError","target":"LoadingError"},{"type":"punctuation","value":")"}] + + ::: + The provided library could not be loaded. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::BadLibraryVersion +:index: 2 +:vis: pub +:toc: BadLibraryVersion +:layout: [{"type":"name","value":"BadLibraryVersion"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":", "},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + The version of the Stan library does not match the version of the rust crate. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::StanThreads +:index: 2 +:vis: pub +:toc: StanThreads +:layout: [{"type":"name","value":"StanThreads"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + The Stan library could not be loaded because it was compiled without threading support. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::InvalidString +:index: 2 +:vis: pub +:toc: InvalidString +:layout: [{"type":"name","value":"InvalidString"},{"type":"punctuation","value":"("},{"type":"link","value":"Utf8Error","target":"Utf8Error"},{"type":"punctuation","value":")"}] + + ::: + Stan returned a string that couldn't be decoded using UTF8. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::ConstructFailed +:index: 2 +:vis: pub +:toc: ConstructFailed +:layout: [{"type":"name","value":"ConstructFailed"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + The model could not be instantiated, possibly because if incorrect data. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::EvaluationFailed +:index: 2 +:vis: pub +:toc: EvaluationFailed +:layout: [{"type":"name","value":"EvaluationFailed"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + Stan returned an error while computing the density. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::SetCallbackFailed +:index: 2 +:vis: pub +:toc: SetCallbackFailed +:layout: [{"type":"name","value":"SetCallbackFailed"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + Setting a print-callback failed. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::ModelCompilingFailed +:index: 2 +:vis: pub +:toc: ModelCompilingFailed +:layout: [{"type":"name","value":"ModelCompilingFailed"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + Compilation of the Stan model shared object failed. + ::: +::::: +:::::{rust:struct} bridgestan::BridgeStanError::DownloadFailed +:index: 2 +:vis: pub +:toc: DownloadFailed +:layout: [{"type":"name","value":"DownloadFailed"},{"type":"punctuation","value":"("},{"type":"link","value":"String","target":"String"},{"type":"punctuation","value":")"}] + + ::: + Downloading BridgeStan's C++ source code from GitHub failed. + ::: +::::: +:::::: + +:::{rubric} Structs and Unions +::: + +::::::{rust:struct} bridgestan::Model +:index: 1 +:vis: pub +:toc: struct Model +:layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"Model"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}] + + ::: + A Stan model instance with data + + + ::: + +:::{rubric} Implementations +::: + +:::::{rust:impl} bridgestan::Model +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Model","target":"Model"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Model + + ::: + ::: + +:::{rubric} Functions +::: + +::::{rust:function} bridgestan::Model::info +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"info"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"punctuation","value":"&"},{"type":"link","value":"CStr","target":"CStr"}] + + ::: + Return information about the compiled model + ::: +:::: +::::{rust:function} bridgestan::Model::log_density +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"log_density"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"propto"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"jacobian"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":">"}] + + ::: + Compute the log of the prior times likelihood density + + Drop jacobian determinant terms of the transformation from unconstrained + to the constrained space if `jacobian == false` and drop terms + of the density that do not depend on the parameters if `propto == true`. + ::: +:::: +::::{rust:function} bridgestan::Model::log_density_gradient +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"log_density_gradient"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"propto"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"jacobian"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"grad"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":">"}] + + ::: + Compute the log of the prior times likelihood density and its gradient + + Drop jacobian determinant terms of the transformation from unconstrained + to the constrained space if `jacobian == false` and drop terms + of the density that do not depend on the parameters if `propto == true`. + + The gradient of the log density will be stored in `grad`. + + *Panics* if the provided buffer has incorrect shape. The gradient buffer `grad` + must have length [`self.param_unc_num()`](Model::param_unc_num). + ::: +:::: +::::{rust:function} bridgestan::Model::log_density_hessian +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"log_density_hessian"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"propto"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"jacobian"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"grad"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"hessian"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":">"}] + + ::: + Compute the log of the prior times likelihood density and its gradient and hessian. + + Drop jacobian determinant terms of the transformation from unconstrained + to the constrained space if `jacobian == false` and drop terms + of the density that do not depend on the parameters if `propto == true`. + + The gradient of the log density will be stored in `grad`, the + hessian is stored in `hessian`. + + *Panics* if the provided buffers have incorrect shapes. The gradient buffer `grad` + must have length [`self.param_unc_num()`](Model::param_unc_num) and the `hessian` + buffer must have length [`self.param_unc_num()`](Model::param_unc_num) `*` + [`self.param_unc_num()`](Model::param_unc_num). + ::: +:::: +::::{rust:function} bridgestan::Model::log_density_hessian_vector_product +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"log_density_hessian_vector_product"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"v"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"propto"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"jacobian"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"hvp"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":">"}] + + ::: + Compute the log of the prior times likelihood density the product of + the Hessian and specified vector. + + Drop jacobian determinant terms of the transformation from unconstrained + to the constrained space if `jacobian == false` and drop terms + of the density that do not depend on the parameters if `propto == true`. + + The product of the Hessian of the log density and the provided vector + will be stored in `hvp`. + + *Panics* if the provided buffer has incorrect shape. The buffer `hvp` + must have length [`self.param_unc_num()`](Model::param_unc_num). + ::: +:::: +::::{rust:function} bridgestan::Model::name +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"name"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"},{"type":"punctuation","value":">"}] + + ::: + Return the name of the model or error if UTF decode fails + ::: +:::: +::::{rust:function} bridgestan::Model::new +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"new"},{"type":"punctuation","value":"<"},{"type":"name","value":"D"},{"type":"punctuation","value":": "},{"type":"link","value":"AsRef","target":"AsRef"},{"type":"punctuation","value":"<"},{"type":"link","value":"CStr","target":"CStr"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":"("},{"type":"name","value":"lib"},{"type":"punctuation","value":": "},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":", "},{"type":"name","value":"data"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"D","target":"D"},{"type":"punctuation","value":">"},{"type":"punctuation","value":", "},{"type":"name","value":"seed"},{"type":"punctuation","value":": "},{"type":"link","value":"u32","target":"u32"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Self","target":"Self"},{"type":"punctuation","value":">"}] + + ::: + Create a new instance of the compiled Stan model. + + Data is specified as a JSON file at the given path, a JSON string literal, + or empty for no data. The seed is used if the model has RNG functions in + the `transformed data` section. + ::: +:::: +::::{rust:function} bridgestan::Model::new_rng +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"new_rng"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"seed"},{"type":"punctuation","value":": "},{"type":"link","value":"u32","target":"u32"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"&"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}] + + ::: + Create a new [`Rng`] random number generator from the library underlying this model. + + This can be used in [`param_constrain()`](Model::param_constrain()) when values + from the `generated quantities` block are desired. + + This instance can only be used with models from the same + Stan library. Invalid usage will otherwise result in a + panic. + ::: +:::: +::::{rust:function} bridgestan::Model::param_constrain +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_constrain"},{"type":"punctuation","value":"<"},{"type":"name","value":"R"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"include_tp"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"include_gq"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"out"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"rng"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"link","value":"R","target":"R"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"}] + + ::: + Map a point in unconstrained parameter space to the constrained space. + + `theta_unc` must contain the point in the unconstrained parameter space. + + If `include_tp` is set the output will also include the transformed + parameters of the Stan model after the parameters. If `include_gq` is + set, we also include the generated quantities at the very end. + + *Panics* if the provided buffer has incorrect shape. The length of the `out` buffer + must be [`self.param_num(include_tp, include_gq)`](Model::param_num). + + *Panics* if `include_gq` is set but no random number generator is provided. + ::: +:::: +::::{rust:function} bridgestan::Model::param_names +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_names"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"include_tp"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"include_gq"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"}] + + ::: + Return a comma-separated sequence of indexed parameter names, + including the transformed parameters and/or generated quantities + as specified. + + The parameters are returned in the order they are declared. + Multivariate parameters are return in column-major (more + generally last-index major) order. Parameter indices are separated + with periods (`.`). For example, `a[3]` is written `a.3` and `b[2, 3]` + as `b.2.3`. The numbering follows Stan and is indexed from 1. + + If `include_tp` is set the names will also include the transformed + parameters of the Stan model after the parameters. If `include_gq` is + set, we also include the names of the generated quantities at + the very end. + ::: +:::: +::::{rust:function} bridgestan::Model::param_num +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_num"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"include_tp"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":", "},{"type":"name","value":"include_gq"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"usize","target":"usize"}] + + ::: + Number of parameters in the model on the constrained scale. + + Will also count transformed parameters (`include_tp`) and generated + quantities (`include_gq`) if requested. + ::: +:::: +::::{rust:function} bridgestan::Model::param_unc_names +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_unc_names"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"}] + + ::: + Return a comma-separated sequence of unconstrained parameters. + Only parameters are unconstrained, so there are no unconstrained + transformed parameters or generated quantities. + + The parameters are returned in the order they are declared. + Multivariate parameters are return in column-major (more + generally last-index major) order. Parameter indices are separated with + periods (`.`). For example, `a[3]` is written `a.3` and `b[2, + 3]` as `b.2.3`. The numbering follows Stan and is indexed from 1. + ::: +:::: +::::{rust:function} bridgestan::Model::param_unc_num +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_unc_num"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"usize","target":"usize"}] + + ::: + Return the number of parameters on the unconstrained scale. + + In particular, this is the size of the slice required by the `log_density` functions. + ::: +:::: +::::{rust:function} bridgestan::Model::param_unconstrain +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_unconstrain"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"theta"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"}] + + ::: + Map a point in constrained parameter space to the unconstrained space. + ::: +:::: +::::{rust:function} bridgestan::Model::param_unconstrain_json +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"param_unconstrain_json"},{"type":"punctuation","value":"<"},{"type":"name","value":"S"},{"type":"punctuation","value":": "},{"type":"link","value":"AsRef","target":"AsRef"},{"type":"punctuation","value":"<"},{"type":"link","value":"CStr","target":"CStr"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"json"},{"type":"punctuation","value":": "},{"type":"link","value":"S","target":"S"},{"type":"punctuation","value":", "},{"type":"name","value":"theta_unc"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"}] + + ::: + Map a constrained point in json format to the unconstrained space. + + The JSON is expected to be in the + [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). + A value for each parameter in the Stan program should be provided, with + dimensions and size corresponding to the Stan program declarations. + ::: +:::: +::::{rust:function} bridgestan::Model::ref_library +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"ref_library"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"punctuation","value":"&"},{"type":"link","value":"StanLibrary","target":"StanLibrary"}] + + ::: + Return a reference to the underlying Stan library + ::: +:::: +::::: +:::::{rust:impl} bridgestan::Model +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":" + "},{"type":"link","value":"Clone","target":"Clone"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Model","target":"Model"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Model + + ::: + ::: + +:::{rubric} Functions +::: + +::::{rust:function} bridgestan::Model::clone_library_ref +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"clone_library_ref"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"T","target":"T"}] + + ::: + Return a clone of the underlying Stan library + ::: +:::: +::::: + +:::{rubric} Traits implemented +::: + +:::::{rust:impl} bridgestan::Model::Sync +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Sync","target":"Sync"},{"type":"punctuation","value":" + "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Sync","target":"Sync"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Model","target":"Model"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Sync for Model + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::Model::Send +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Send","target":"Send"},{"type":"punctuation","value":" + "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Send","target":"Send"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Model","target":"Model"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Send for Model + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::Model::Drop +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Drop","target":"Drop"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Model","target":"Model"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Drop for Model + + ::: + ::: +::::: +:::::: +::::::{rust:struct} bridgestan::Rng +:index: 1 +:vis: pub +:toc: struct Rng +:layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"Rng"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}] + + ::: + A random number generator for Stan models. + This is only used in the [`Model::param_constrain()`](Model::param_constrain) method + of the model when requesting values from the `generated quantities` block. + Different threads should use different instances. + + + ::: + +:::{rubric} Implementations +::: + +:::::{rust:impl} bridgestan::Rng +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Rng + + ::: + ::: + +:::{rubric} Functions +::: + +::::{rust:function} bridgestan::Rng::new +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"new"},{"type":"punctuation","value":"("},{"type":"name","value":"lib"},{"type":"punctuation","value":": "},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":", "},{"type":"name","value":"seed"},{"type":"punctuation","value":": "},{"type":"link","value":"u32","target":"u32"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Self","target":"Self"},{"type":"punctuation","value":">"}] + + ::: + ::: +:::: +::::: + +:::{rubric} Traits implemented +::: + +:::::{rust:impl} bridgestan::Rng::Sync +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Sync","target":"Sync"},{"type":"punctuation","value":" + "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Sync","target":"Sync"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Sync for Rng + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::Rng::Send +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Send","target":"Send"},{"type":"punctuation","value":" + "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Send","target":"Send"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Send for Rng + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::Rng::Drop +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"punctuation","value":"<"},{"type":"name","value":"T"},{"type":"punctuation","value":": "},{"type":"link","value":"Borrow","target":"Borrow"},{"type":"punctuation","value":"<"},{"type":"link","value":"StanLibrary","target":"StanLibrary"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"space"},{"type":"link","value":"Drop","target":"Drop"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"Rng","target":"Rng"},{"type":"punctuation","value":"<"},{"type":"link","value":"T","target":"T"},{"type":"punctuation","value":">"}] +:toc: impl Drop for Rng + + ::: + ::: +::::: +:::::: +::::::{rust:struct} bridgestan::StanLibrary +:index: 1 +:vis: pub +:toc: struct StanLibrary +:layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"StanLibrary"}] + + ::: + A loaded shared library for a Stan model + + + ::: + +:::{rubric} Implementations +::: + +:::::{rust:impl} bridgestan::StanLibrary +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"StanLibrary","target":"StanLibrary"}] +:toc: impl StanLibrary + + ::: + ::: + +:::{rubric} Functions +::: + +::::{rust:function} bridgestan::StanLibrary::set_print_callback +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"set_print_callback"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"keyword","value":"self"},{"type":"punctuation","value":", "},{"type":"name","value":"callback"},{"type":"punctuation","value":": "},{"type":"link","value":"StanPrintCallback","target":"StanPrintCallback"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Result","target":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"}] + + ::: + Provide a callback function to be called when Stan prints a message + + ## Safety + + The provided function must never panic. + + Since the call is protected by a mutex internally, it does not + need to be thread safe. + ::: +:::: +::::{rust:function} bridgestan::StanLibrary::unload_library +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"unload_library"},{"type":"punctuation","value":"("},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"keyword","value":"self"},{"type":"punctuation","value":")"}] + + ::: + Unload the Stan library. + + ## Safety + + There seem to be issues around unloading libraries in threaded + code that are not fully understood: + + ::: +:::: +::::: + +:::{rubric} Traits implemented +::: + +:::::{rust:impl} bridgestan::StanLibrary::Send +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"Send","target":"Send"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"StanLibrary","target":"StanLibrary"}] +:toc: impl Send for StanLibrary + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::StanLibrary::Sync +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"Sync","target":"Sync"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"StanLibrary","target":"StanLibrary"}] +:toc: impl Sync for StanLibrary + + ::: + ::: +::::: +:::::{rust:impl} bridgestan::StanLibrary::Drop +:index: -1 +:vis: pub +:layout: [{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"Drop","target":"Drop"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"StanLibrary","target":"StanLibrary"}] +:toc: impl Drop for StanLibrary + + ::: + ::: +::::: +:::::: diff --git a/docs/languages/c-api.rst b/docs/languages/c-api.rst index d1a9b411..411677cb 100644 --- a/docs/languages/c-api.rst +++ b/docs/languages/c-api.rst @@ -16,8 +16,7 @@ Example Program Two example programs are provided alongside the BridgeStan source in :file:`c-example/`. Details for building the example can be found in :file:`c-example/Makefile`. -The first assumes you wish to link a specific model into the program, -and the second demonstrates how to load a model at runtime +If you wish to link a specific model into the program: .. raw:: html @@ -32,6 +31,7 @@ and the second demonstrates how to load a model at runtime +Alternatively, if you wish to load a model at runtime: .. raw:: html diff --git a/docs/languages/julia.md b/docs/languages/julia.md index e46578e3..90e7047d 100644 --- a/docs/languages/julia.md +++ b/docs/languages/julia.md @@ -254,7 +254,7 @@ param_unconstrain_json(sm, theta) This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). This allocates new memory for the output each call. See [`param_unconstrain_json!`](julia.md#BridgeStan.param_unconstrain_json!) for a version which allows re-using existing memory. @@ -462,7 +462,7 @@ param_unconstrain_json!(sm, theta, out) This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). The result is stored in the vector `out`, and a reference is returned. See [`param_unconstrain_json`](julia.md#BridgeStan.param_unconstrain_json) for a version which allocates fresh memory. diff --git a/docs/languages/rust.md b/docs/languages/rust.md new file mode 100644 index 00000000..6073117d --- /dev/null +++ b/docs/languages/rust.md @@ -0,0 +1,41 @@ +# Rust Interface + +--- + +## Installation + +The BridgeStan Rust client is available on [crates.io](https://crates.io/crates/bridgestan) and via `cargo`: + +```shell +cargo add bridgestan +``` + +A copy of the BridgeStan C++ sources is needed to compile models. This can be downloaded to +`~/.bridgestan/` automatically if you use the `download-bridgestan-src` feature. +Otherwise, it can be downloaded manually (see [Getting Started](../getting-started.rst)). + +Note that the system pre-requisites from the [Getting Started guide](../getting-started.rst) +are still required and will not be automatically installed by this method. + +## Example Program + +An example program is provided alongside the Rust crate in `examples/example.rs`: + +
+Show example.rs + +```{literalinclude} ../../rust/examples/example.rs +:language: Rust +``` + +
+ + +API Reference +------------- + +This is also available [on docs.rs](https://docs.rs/bridgestan) + +```{include} ./_rust/bridgestan/lib.md +:start-line: 2 +``` diff --git a/docs/languages/rust.rst b/docs/languages/rust.rst deleted file mode 100644 index 5b2cf158..00000000 --- a/docs/languages/rust.rst +++ /dev/null @@ -1,46 +0,0 @@ -Rust Interface -============== - -`See the BridgeStan Crate documentation on docs.rs `__ - ----- - -Installation ------------- - -The BridgeStan Rust client is available on `crates.io `__ and via :command:`cargo`: - -.. code-block:: shell - - cargo add bridgestan - -A copy of the BridgeStan C++ sources is needed to compile models. This can be downloaded to -:file:`~/.bridgestan/` automatically if you use the ``download-bridgestan-src`` feature. -Otherwise, it can be downloaded manually (see :doc:`../getting-started`). - -Note that the system pre-requisites from the :doc:`Getting Started guide <../getting-started>` -are still required and will not be automatically installed by this method. - -Example Program ---------------- - -An example program is provided alongside the Rust crate in :file:`examples/example.rs`: - -.. raw:: html - -
- Show example.rs - - -.. literalinclude:: ../../rust/examples/example.rs - :language: Rust - -.. raw:: html - -
- - -API Reference -------------- - -See docs.rs for the full API reference: ``__ diff --git a/docs/requirements.txt b/docs/requirements.txt index 13de66a5..24df4ce4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ - sphinx>5 nbsphinx ipython @@ -8,3 +7,4 @@ sphinx-copybutton pydata-sphinx-theme breathe myst-parser +sphinxcontrib-rust>=0.8.1 diff --git a/julia/src/model.jl b/julia/src/model.jl index 22cfafb6..6fb92aed 100644 --- a/julia/src/model.jl +++ b/julia/src/model.jl @@ -406,7 +406,7 @@ end This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). The result is stored in the vector `out`, and a reference is returned. See [`param_unconstrain_json`](@ref) for a version which allocates fresh memory. @@ -438,7 +438,7 @@ end This accepts a JSON string of constrained parameters and returns the unconstrained parameters. -The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). +The JSON is expected to be in the [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json_apdx.html). This allocates new memory for the output each call. See [`param_unconstrain_json!`](@ref) for a version which allows diff --git a/python/bridgestan/model.py b/python/bridgestan/model.py index d7c4e490..01d8ed05 100644 --- a/python/bridgestan/model.py +++ b/python/bridgestan/model.py @@ -508,8 +508,8 @@ def param_unconstrain_json( ) -> FloatArray: """ Return an array of the unconstrained parameters derived from the - specified JSON formatted data. See the *CmdStan Reference - Manual* for the schema definition used. + specified JSON formatted data. + The JSON is expected to be in the `JSON Format for CmdStan `__. :param theta_json: The JSON encoded constrained parameters. :param out: A location into which the result is stored. If diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 5ebce78d..5c919af1 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -31,3 +31,6 @@ env_logger = "0.11" [[example]] name = "example" + +[package.metadata.docs.rs] +all-features = true diff --git a/rust/src/bs_safe.rs b/rust/src/bs_safe.rs index 01db49b6..6d9e6c9d 100644 --- a/rust/src/bs_safe.rs +++ b/rust/src/bs_safe.rs @@ -46,7 +46,7 @@ pub type StanPrintCallback = extern "C" fn(*const c_char, usize); impl StanLibrary { /// Provide a callback function to be called when Stan prints a message /// - /// # Safety + /// ## Safety /// /// The provided function must never panic. /// @@ -65,7 +65,7 @@ impl StanLibrary { /// Unload the Stan library. /// - /// # Safety + /// ## Safety /// /// There seem to be issues around unloading libraries in threaded /// code that are not fully understood: @@ -162,7 +162,7 @@ unsafe impl> Sync for Model {} unsafe impl> Send for Model {} /// A random number generator for Stan models. -/// This is only used in the `param_contrain` method +/// This is only used in the [`Model::param_constrain()`](Model::param_constrain) method /// of the model when requesting values from the `generated quantities` block. /// Different threads should use different instances. pub struct Rng> { @@ -287,10 +287,10 @@ impl> Model { self.lib.borrow() } - /// Create a new `Rng` random number generator from the library underlying this model. + /// Create a new [`Rng`] random number generator from the library underlying this model. /// - /// This can be used in `param_constrain` when values from the `generated quantities` - /// block are desired. + /// This can be used in [`param_constrain()`](Model::param_constrain()) when values + /// from the `generated quantities` block are desired. /// /// This instance can only be used with models from the same /// Stan library. Invalid usage will otherwise result in a @@ -367,7 +367,7 @@ impl> Model { /// Return the number of parameters on the unconstrained scale. /// - /// In particular, this is the size of the slice required by the log_density functions. + /// In particular, this is the size of the slice required by the `log_density` functions. pub fn param_unc_num(&self) -> usize { unsafe { self.ffi_lib().bs_param_unc_num(self.model.as_ptr()) } .try_into() @@ -416,7 +416,7 @@ impl> Model { /// The gradient of the log density will be stored in `grad`. /// /// *Panics* if the provided buffer has incorrect shape. The gradient buffer `grad` - /// must have length `self.param_unc_num()`. + /// must have length [`self.param_unc_num()`](Model::param_unc_num). pub fn log_density_gradient( &self, theta_unc: &[f64], @@ -468,8 +468,9 @@ impl> Model { /// hessian is stored in `hessian`. /// /// *Panics* if the provided buffers have incorrect shapes. The gradient buffer `grad` - /// must have length `self.param_unc_num()` and the `hessian` buffer must - /// have length `self.param_unc_num() * self.param_unc_num()`. + /// must have length [`self.param_unc_num()`](Model::param_unc_num) and the `hessian` + /// buffer must have length [`self.param_unc_num()`](Model::param_unc_num) `*` + /// [`self.param_unc_num()`](Model::param_unc_num). pub fn log_density_hessian( &self, theta_unc: &[f64], @@ -529,7 +530,7 @@ impl> Model { /// will be stored in `hvp`. /// /// *Panics* if the provided buffer has incorrect shape. The buffer `hvp` - /// must have length `self.param_unc_num()`. + /// must have length [`self.param_unc_num()`](Model::param_unc_num). pub fn log_density_hessian_vector_product( &self, theta_unc: &[f64], @@ -587,7 +588,8 @@ impl> Model { /// set, we also include the generated quantities at the very end. /// /// *Panics* if the provided buffer has incorrect shape. The length of the `out` buffer - /// `self.param_num(include_tp, include_gq)`. + /// must be [`self.param_num(include_tp, include_gq)`](Model::param_num). + /// /// *Panics* if `include_gq` is set but no random number generator is provided. pub fn param_constrain>( &self, @@ -674,7 +676,8 @@ impl> Model { /// Map a constrained point in json format to the unconstrained space. /// - /// The JSON schema assumed is fully defined in the *CmdStan Reference Manual*. + /// The JSON is expected to be in the + /// [JSON Format for CmdStan](https://mc-stan.org/docs/cmdstan-guide/json.html). /// A value for each parameter in the Stan program should be provided, with /// dimensions and size corresponding to the Stan program declarations. pub fn param_unconstrain_json>( diff --git a/rust/src/compile.rs b/rust/src/compile.rs index b1fe7dd7..bec68b40 100644 --- a/rust/src/compile.rs +++ b/rust/src/compile.rs @@ -6,9 +6,9 @@ use std::path::{Path, PathBuf}; const MAKE: &str = "make"; /// Compile a Stan Model. Requires a path to the BridgeStan sources (can be -/// downloaded with [`download_bridgestan_src`](crate::download_bridgestan_src) if that feature -/// is enabled), a path to the `.stan` file, and additional arguments -/// for the Stan compiler and the make command. +/// downloaded with [`download_bridgestan_src`](crate::download_bridgestan_src) +/// if that feature is enabled), a path to the `.stan` file, and +/// additional arguments for the Stan compiler and the `make` command. pub fn compile_model( bs_path: &Path, stan_file: &Path, diff --git a/rust/src/download.rs b/rust/src/download.rs index 29b02bf6..50bd72bc 100644 --- a/rust/src/download.rs +++ b/rust/src/download.rs @@ -7,6 +7,7 @@ use tar::Archive; /// Download and unzip the BridgeStan source distribution for this version /// to `~/.bridgestan/bridgestan-$VERSION`. +/// Requires feature `download-bridgestan-src`. pub fn download_bridgestan_src() -> Result { let homedir = dirs::home_dir().unwrap_or(temp_dir()); diff --git a/src/bridgestan.h b/src/bridgestan.h index 780a6c18..72629ac7 100644 --- a/src/bridgestan.h +++ b/src/bridgestan.h @@ -40,8 +40,9 @@ BS_PUBLIC extern const int bs_patch_version; /** * Construct an instance of a model wrapper. - * Data must be encoded in JSON as indicated - * in the *CmdStan Reference Manual*. + * Data must be encoded in JSON in the + * JSON Format for + * CmdStan. * * @param[in] data C-style string. This is either a * path to JSON-encoded data file (must end with ".json"), @@ -205,8 +206,10 @@ BS_PUBLIC int bs_param_unconstrain(const bs_model* m, const double* theta, /** * Set the sequence of unconstrained parameters based on the JSON * specification of the constrained parameters, and return a return - * code of 0 for success and -1 for failure. The JSON schema assumed - * is fully defined in the *CmdStan Reference Manual*. + * code of 0 for success and -1 for failure. + * The JSON is expected to be in the + * JSON Format for + * CmdStan. * * @param[in] m pointer to model structure * @param[in] json JSON-encoded constrained parameters