Merge branch 'main' into joss

.github/workflows/main.yaml

@@ -14,6 +14,7 @@ jobs:
   build:
     runs-on: ${{matrix.os}}
     strategy:
+      fail-fast: false
       matrix:
         os: [windows-latest, ubuntu-latest, macos-latest]
     env:
@@ -103,6 +104,10 @@ jobs:
           pip install pytest
           pip install .
 
+      - name: Test import
+        run: |
+          python -c "import bridgestan"
+
       - name: Run tests
         run: |
           cd python/
@@ -155,6 +160,12 @@ jobs:
           path: ./test_models/
           key: ${{ hashFiles('**/*.stan', 'src/*', 'stan/src/stan/version.hpp', 'Makefile') }}-${{ matrix.os }}-v${{ env.CACHE_VERSION }}
 
+      - name: Check import
+        run: |
+          cd julia/
+          julia --project=. -e "using Pkg; Pkg.instantiate()"
+          julia --project=. -e "using BridgeStan"
+
       - name: Run tests
         run: |
           cd julia/
@@ -272,5 +283,5 @@ jobs:
         run: |
           cargo clippy
           cargo fmt --check
-          cargo run --example=make_model
-          cargo test --verbose
+          cargo run --example=example
+          cargo test --verbose

.github/workflows/release.yaml

@@ -33,12 +33,19 @@ jobs:
       - name: Set up Julia
         uses: julia-actions/setup-julia@v1
 
+      - name: Install LLVM and Clang
+        uses: KyleMayes/install-llvm-action@v1
+        with:
+          version: "15.0"
+          directory: ${{ runner.temp }}/llvm
+
       - name: Update version numbers
         if: ${{ !inputs.is_rerun }}
         run: |
           sed -i 's/Version:.*/Version: ${{ inputs.new_version }}/' R/DESCRIPTION
           sed -i 's/version = .*/version = "${{ inputs.new_version }}"/' julia/Project.toml
           sed -i 's/__version__ = .*/__version__ = "${{ inputs.new_version }}"/' python/bridgestan/__version.py
+          sed -i 's/^version = .*/version = "${{ inputs.new_version }}"/' rust/Cargo.toml
 
           sed -i 's/#define BRIDGESTAN_MAJOR .*/#define BRIDGESTAN_MAJOR '"$(echo ${{ inputs.new_version }} | cut -d. -f1)"'/' src/version.hpp
           sed -i 's/#define BRIDGESTAN_MINOR .*/#define BRIDGESTAN_MINOR '"$(echo ${{ inputs.new_version }} | cut -d. -f2)"'/' src/version.hpp
@@ -80,10 +87,11 @@ jobs:
         with:
           name: release-artifacts
           path: |
-            python/dist/
+            python/dist/*.whl
             bridgestan-*.tar.gz
 
       - name: Create release
+        if: ${{ !inputs.is_rerun }}
         uses: ncipollo/release-action@v1
         with:
           artifacts: "bridgestan-*.tar.gz,python/dist/*"
@@ -97,12 +105,23 @@ jobs:
 
       - name: Upload PyPI wheels
         if: ${{ !inputs.dry_run }}
-        uses: pypa/gh-action-pypi-publish@v1.8.6
+        uses: pypa/gh-action-pypi-publish@v1.8.7
         with:
           password: ${{ secrets.PYPI_TOKEN }}
           packages_dir: python/dist/
           skip_existing: true
 
+      - name: Publish Rust crate
+        if: ${{ !inputs.dry_run }}
+        run: |
+          cd rust/
+          cargo publish --token ${CRATES_TOKEN}
+        env:
+          # clang is necessary unless we want to do --no-verify
+          LIBCLANG_PATH: ${{ runner.temp }}/llvm/lib
+          LLVM_CONFIG_PATH: ${{ runner.temp }}/llvm/bin/llvm-config
+          CRATES_TOKEN: ${{ secrets.CRATES_TOKEN }}
+
       - name: Create JuliaRegistration comment
         if: ${{ !inputs.dry_run }}
         uses: peter-evans/commit-comment@v2

CONTRIBUTING.md

@@ -71,8 +71,18 @@ We use [Gnu make](https://www.gnu.org/software/make/) for builds.  If you have p
     * [Test](https://docs.julialang.org/en/v1/stdlib/Test/)
     * [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/)
 
-* Julia code is formatted using [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl).
+* Julia code is formatted using[JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl).
 
+* Julia's multi-threading capabilities allow different processors/threads to
+make simultaneous calls to the BridgeStan API.  Such capabilities require the
+target Stan program to be compiled with `STAN_THREADS=true`, see the function
+[compile_model](https://roualdes.github.io/bridgestan/latest/languages/julia.html#BridgeStan.compile_model)
+for more details.  The Julia interface tests this feature and thus requires
+`STAN_THREADS=true` for the tests to run successfully.
+
+### Rust development
+
+* Rust development is based on `cargo`, which should handle dependencies, testing, and formatting.
 
 ## Proposing a new interface language
 

Makefile

@@ -16,6 +16,7 @@ INC_FIRST ?= -I $(STAN)src -I $(RAPIDJSON)
 
 ## Set -fPIC globally since we're always building a shared library
 CXXFLAGS += -fPIC
+CXXFLAGS_SUNDIALS += -fPIC
 
 ## set flags for stanc compiler (math calls MIGHT? set STAN_OPENCL)
 ifdef STAN_OPENCL
@@ -56,12 +57,12 @@ $(BRIDGE_O) : $(BRIDGE_DEPS)
 .PRECIOUS: %.hpp
 
 ## builds executable (suffix depends on platform)
-%_model.so : %.hpp $(BRIDGE_O) $(LIBSUNDIALS) $(MPI_TARGETS) $(TBB_TARGETS)
+%_model.so : %.hpp $(BRIDGE_O) $(SUNDIALS_TARGETS) $(MPI_TARGETS) $(TBB_TARGETS)
 	@echo ''
 	@echo '--- Compiling C++ code ---'
 	$(COMPILE.cpp) -x c++ -o $(subst  \,/,$*).o $(subst \,/,$<)
 	@echo '--- Linking C++ code ---'
-	$(LINK.cpp) -shared -lm -o $(patsubst %.hpp, %_model.so, $(subst \,/,$<)) $(subst \,/,$*.o) $(BRIDGE_O) $(LDLIBS) $(LIBSUNDIALS) $(MPI_TARGETS) $(TBB_TARGETS)
+	$(LINK.cpp) -shared -lm -o $(patsubst %.hpp, %_model.so, $(subst \,/,$<)) $(subst \,/,$*.o) $(BRIDGE_O) $(LDLIBS) $(SUNDIALS_TARGETS) $(MPI_TARGETS) $(TBB_TARGETS)
 	$(RM) $(subst  \,/,$*).o
 
 .PHONY: docs
@@ -94,7 +95,7 @@ stan-update-remote:
 # print compilation command line config
 .PHONY: compile_info
 compile_info:
-	@echo '$(LINK.cpp) $(BRIDGE_O) $(LDLIBS) $(LIBSUNDIALS) $(MPI_TARGETS) $(TBB_TARGETS)'
+	@echo '$(LINK.cpp) $(BRIDGE_O) $(LDLIBS) $(SUNDIALS_TARGETS) $(MPI_TARGETS) $(TBB_TARGETS)'
 
 ## print value of makefile variable (e.g., make print-TBB_TARGETS)
 .PHONY: print-%

R/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: bridgestan
 Title: BridgeStan, Accessing Stan Model Functions in R
-Version: 2.0.0
+Version: 2.1.1
 Authors@R:
     person(given="Brian", family="Ward", , "bward@flatironinstitute.org", role = c("aut", "cre"))
 License: BSD_3_clause

README.md

@@ -3,7 +3,7 @@
 [![DOCS](https://img.shields.io/badge/docs-latest-blue)](https://roualdes.github.io/bridgestan/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7760173.svg)](https://doi.org/10.5281/zenodo.7760173) [![CI](https://github.com/roualdes/bridgestan/actions/workflows/main.yaml/badge.svg)](https://github.com/roualdes/bridgestan/actions/workflows/main.yaml)
 
 BridgeStan provides efficient in-memory access through Python, Julia,
-and R to the methods of a [Stan](https://mc-stan.org) model, including
+Rust, and R to the methods of a [Stan](https://mc-stan.org) model, including
 log densities, gradients, Hessians, and constraining and unconstraining
 transforms.  The motivation was developing inference algorithms in
 higher-level languages for arbitrary Stan models.
@@ -60,14 +60,16 @@ to download the appropriate Stan compiler for your platform into
 ### Example programs
 
 This repository includes examples of calling Stan through BridgeStan
-in Python, Julia, R, and C.
+in Python, Julia, R, Rust, and C.
 
 * From Python: [`example.py`](python/example.py)
 
 * From Julia: [`example.jl`](julia/example.jl)
 
 * From R: [`example.r`](R/example.R)
 
+* From Rust: [`example.rs`](rust/examples/example.rs)
+
 * From C: [`example.c`](c-example/example.c)
 
 Examples of other functionality can be found in the `test` folder for each interface.
@@ -81,3 +83,6 @@ API, which in turn was derived from
 
 Thanks to Sebastian Weber (GitHub [@wds15](https://github.com/wds15))
 for enabling multi-threaded calls from Julia to a single Stan model instance.
+
+Thanks to Adrian Seyboldt (GitHub [@aseyboldt](https://github.com/aseyboldt))
+for providing the Rust wrapper.

docs/_static/css/custom.css

@@ -0,0 +1,7 @@
+html[data-theme="light"] {
+    --pst-color-inline-code: #008000;
+}
+
+html[data-theme="dark"] {
+    --pst-color-inline-code: #659157;
+}

docs/_static/switcher.json

@@ -4,6 +4,16 @@
         "version": "latest",
         "url": "https://roualdes.github.io/bridgestan/latest/"
     },
+    {
+        "name": "v2.1.1",
+        "version": "v2.1.1",
+        "url": "https://roualdes.github.io/bridgestan/v2.1.1/"
+    },
+    {
+        "name": "v2.1.0",
+        "version": "v2.1.0",
+        "url": "https://roualdes.github.io/bridgestan/v2.1.0/"
+    },
     {
         "name": "v2.0.0",
         "version": "v2.0.0",

docs/conf.py

@@ -53,6 +53,7 @@
 html_static_path = ["_static"]
 html_css_files = [
     "css/Documenter.css",
+    "css/custom.css",
 ]
 
 html_show_sphinx = False

docs/getting-started.rst

@@ -8,7 +8,7 @@ Requirement: C++ toolchain
 Stan requires a C++ tool chain consisting of
 
 * A C++14 compiler. On Windows, MSCV is *not* supported, so something like MinGW GCC is required.
-* The Gnu ``make`` utility for \*nix *or* ``mingw32-make`` for Windows
+* The Gnu :command:`make` utility for \*nix *or* :command:`mingw32-make` for Windows
 
 Here are complete instructions by platform for installing both, from the CmdStan installation instructions.
 
@@ -24,7 +24,8 @@ and no additional dependencies are required to be installed separately for the C
 
 As of version 1.0.2, the :doc:`Julia <languages/julia>` and
 :doc:`Python <languages/python>` interfaces will download
-the source for you, so this section is optional.
+the source for you the first time you compile a model, so
+this section is optional.
 
 Downloading a released archive
 ______________________________
@@ -36,10 +37,10 @@ To use these, simply download the file associated with the version you wish to u
 and unzip its contents into the folder you would like BridgeStan to be in.
 
 
-Installing the latest version with ``git``
-__________________________________________
+Installing the latest version with :command:`git`
+_________________________________________________
 
-If you have ``git`` installed, you may download BridgeStan by navigating to the folder you'd like
+If you have :command:`git` installed, you may download BridgeStan by navigating to the folder you'd like
 BridgeStan to be in and running
 
 .. code-block:: shell
@@ -64,10 +65,10 @@ a terminal in your BridgeStan folder and running
     # Windows
     mingw32-make.exe test_models/multi/multi_model.so
 
-This will compile the file ``test_models/multi/multi.stan`` into a shared library object for use with BridgeStan.
+This will compile the file :file:`test_models/multi/multi.stan` into a shared library object for use with BridgeStan.
 This will require internet access the first time you run it in order
 to download the appropriate Stan compiler for your platform into
-``<bridgestan-dir>/bin/stanc[.exe]``
+:file:`{<bridgestan-dir>}/bin/stanc{[.exe]}`
 
 Installing an Interface
 -----------------------
@@ -81,10 +82,10 @@ Optional: Customizing BridgeStan
 BridgeStan has many compiler flags and options set by default. Many of these defaults
 are the same as those used by the CmdStan interface to Stan.
 You can override the defaults or add new flags
-on the command line when invoking ``make``, or make them persistent by
-creating or editing the file ``<bridgestan dir>/make/local``.
+on the command line when invoking :command:`make`, or make them persistent by
+creating or editing the file :file:`{<bridgestan dir>}/make/local`.
 
-For example, setting the contents of ``make/local`` to the following
+For example, setting the contents of :file:`make/local` to the following
 includes compiler flags for optimization level and architecture.
 
 .. code-block:: Makefile
@@ -94,7 +95,7 @@ includes compiler flags for optimization level and architecture.
     # Adding other arbitrary C++ compiler flags
     CXXFLAGS+= -march=native
 
-Flags for ``stanc3`` can also be set here
+Flags for :command:`stanc3` can also be set here
 
 .. code-block:: Makefile
 
@@ -106,7 +107,7 @@ ________________________________________
 
 In order for Python or Julia to be able to call a single Stan model
 concurrently from multiple threads or for a Stan model to execute its
-own code in parallel, the following flag must be set in ``make/local``
+own code in parallel, the following flag must be set in :file:`make/local`
 or on the command line.
 
 .. code-block:: Makefile
@@ -116,7 +117,7 @@ or on the command line.
 
 Note that this flag changes a lot of the internals of the Stan library
 and as such, **all models used in the same process should have the same
-setting**. Mixing models which have ``STAN_THREADS`` enabled with those that do not
+setting**. Mixing models which have :makevar:`STAN_THREADS` enabled with those that do not
 will most likely lead to segmentation faults or other crashes.
 
 Additional flags, such as those for MPI and OpenCL, are covered in the
@@ -131,12 +132,12 @@ to be computed directly, particularly models which use implicit functions like t
 or ODE integrators.
 
 If your Stan model does not use these features, you can enable autodiff Hessians by
-setting the compile-time flag ``BRIDGESTAN_AD_HESSIAN=true`` in the invocation to ``make``.
-This can be set in ``make/local`` if you wish to use it by default.
+setting the compile-time flag ``BRIDGESTAN_AD_HESSIAN=true`` in the invocation to :command:`make`.
+This can be set in :file:`make/local` if you wish to use it by default.
 
 This value is reported by the ``model_info`` function if you would like to check at run time
 whether Hessians are computed with nested autodiff or with finite differences. Similar to
-``STAN_THREADS``, it is not advised to mix models which use autodiff Hessians with those that
+:makevar:`STAN_THREADS`, it is not advised to mix models which use autodiff Hessians with those that
 do not in the same program.
 
 Autodiff Hessians may be faster than finite differences depending on your model, and will
@@ -147,21 +148,21 @@ __________________________
 
 If you wish to use BridgeStan for an older released version, all you need to do is
 
-1. Set ``STANC3_VERSION`` in ``make/local`` to your desired version, e.g. ``v2.26.0``
+1. Set :makevar:`STANC3_VERSION` in :file:`make/local` to your desired version, e.g. ``v2.26.0``
 2. Go into the ``stan`` submodule and run ``git checkout release/VERSION``, e.g. ``release/v2.26.0``
 3. Also in the ``stan`` submodule, run ``make math-update``
 4. In the top level BridgeStan directory, run ``make clean``
 
 To return to the version of Stan currently used by BridgeStan, you can run ``make stan-update`` from the top level directory
-and remove ``STANC3_VERSION`` from your ``make/local`` file, before running ``make clean`` again.
+and remove :makevar:`STANC3_VERSION` from your ``make/local`` file, before running ``make clean`` again.
 
 Using Pre-Existing Stan Installations
 _____________________________________
 
 If you wish to use BridgeStan with a pre-existing download of the Stan repository, or with
-a custom fork or branch, you can set the ``STAN`` (and, optionally, ``MATH``) variables to the
-path to your existing copy in calls to ``make``, or more permanently by setting them in a
-``make/local`` file as described above.
+a custom fork or branch, you can set the :makevar:`STAN` (and, optionally, :makevar:`MATH`) variables to the
+path to your existing copy in calls to :command:`make`, or more permanently by setting them in a
+:file:`make/local` file as described above.
 
 The easiest way to use a custom stanc3 is to place the built executable at
-``bin/stanc[.exe]``.
+:file:`bin/stanc{[.exe]}`.

docs/index.rst

@@ -1,13 +1,9 @@
-.. BridgeStan documentation master file, created by
-   sphinx-quickstart on Fri Sep  2 11:44:11 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 Welcome to BridgeStan's documentation!
 ======================================
 
 BridgeStan provides efficient in-memory access through Python, Julia,
-and R to the methods of a `Stan <https://mc-stan.org>`__ model, including
+R, and Rust to the methods of a `Stan <https://mc-stan.org>`__ model, including
 log densities, gradients, Hessians, and constraining and unconstraining
 transforms.
 

docs/internals/documentation.rst

@@ -11,7 +11,7 @@ generation (powered by `Sphinx <https://www.sphinx-doc.org/en/master/>`__) autom
 combines these together into the documentation you are reading now.
 
 To build the documentation, you can run ``make docs`` in the top-level directory.
-This places the files in ``docs/_build/html``. At a minimum, the following must be installed:
+This places the files in :file:`docs/_build/html`. At a minimum, the following must be installed:
 
 * The Python interface to BridgeStan
 * `Sphinx 5.0 or above <https://www.sphinx-doc.org/en/master/>`__
@@ -28,6 +28,6 @@ If you wish to build the C++ portions of the documentation, you should also have
 * `Breathe <https://breathe.readthedocs.io/en/stable/index.html>`__
 
 Similarly, the Julia documentation will only update if Julia is installed. Julia
-documentation is written in ``julia/docs/src/julia.md``. We then build
+documentation is written in :file:`julia/docs/src/julia.md`. We then build
 this with `DocumenterMarkdown.jl <https://github.com/JuliaDocs/DocumenterMarkdown.jl>`__,
-and the output is placed in ``docs/languages/julia.md``.
+and the output is placed in :file:`docs/languages/julia.md`.