CmdStan-RUS Bilayer Demonstration Files and Code
Description
This repository contains all of necessary input files for the CmdStan-RUS Bilayer code to reproduce the dual-likelihood, optimization plus Laplace approximation fits, of virtual bilayer "VB-4" and experimental bilayer "EB-1" published in: B.R. Goodlet, B. Bales and T.M. Pollock, "A New Elastic Characterization Method for Anisotropic Bilayer Specimens via Bayesian Resonant Ultrasound Spectroscopy", Ultrasonics (2021). The .stan buildfile is highly annotated with: - block and function descriptions - input data for 2 experiments (exp_1 = bare substrate, exp_2 = bilayer specimen) - parameter definitions, bounds, and units - transformed parameters (coordinates) - prior distributions - code for both a "normal" and "log-normal" noise model Datafile-vb4.dat and Datafile-eb1.dat each give the input data for exp_1 and exp_2 - Note: the computational precision for these models, particularly the bilayer model, are set to compute "publish quality" fits that may require 32+ GB of RAM and a runtime in excess of 24 hours. - To test the code on a computer with less RAM, try a low-precision fit using: P_exp1 = 10, and PX_exp2 = 12, PY_exp2 = 12, PZ_sub_exp2 = 1, PZ_coat_exp2 = 0 (and if the fit completes, expect some biased parameter estimates due to insufficient P) - If the code crashes before a single iteration is written to the output.csv file, you may be (i) exceeding the RAM of your computer, or (ii) if you increased the computational precision of the fit, you may be exceeding the computational limits of the code Runfile-vb4.txt and Runfile-eb1.txt each give 3 sets of commands: the first two conduct a optimization (using the LBFGS algorithm) followed by a Laplace approximation, the third conducts a full HMC inference (using the NUTS algorithm) - The first set of commands does not specify initial conditions, so random initial conditions are generated, followed by 1000 optimization iterations and 1000 laplace draws - The second set of commands specifies that "init-vb4.dat" be used for initial conditions, followed by 1000 optimization iterations and 1000 laplace draws - The third set of commands sample the posterior with HMC, using 250 warm-up samples (a bare minimum for successful HMC auto-tuning) followed by 500 sampling samples (from which posterior distributions are computed) - Be advised: HMC sampling of the posterior (as opposed to Laplace approximations of the posterior) can require 10 to 100 times as many forward model evaluations, with "publish quality" fits taking 30+ days of continuous compute time. init-vb4.dat details how initial conditions are specified - Any or all of the parameters (defined in the .stan buildfile) can be specified with initial conditions - Initial conditions for transformed parameters are ignored
Files
Steps to reproduce
1. Install CmdStan-RUS from: https://github.com/bbbales2/cmdstan-rus - Instructions for installing CmdStan (the command line interface to Stan) can be found here: https://mc-stan.org/docs/2_24/cmdstan-guide/cmdstan-installation.html which should get your system setup for cloning the CmdStan-RUS repository (from the github link above) in the same manner as Step 1.3. 2. Place the necessary "Experimental data files" into the /cmdstan-rus/examples directory - This includes at least one .stan buildfile, one datafile.dat, and one runfile.txt. - Optionally, a initialization.dat file can be used to specify initial conditions for estimated parameters - Note: simplified example files can also be found in the /examples directory 3. "Make" the .stan buildfile into compiled code with the following terminal command: make examples/buildfile - This command works from the /CmdStan-RUS directory, one level up from /CmdStan-RUS/examples folder. - Note: a .stan buildfile is only compiled once before its first use 4. Initiate a fit using by executing the Runfile.txt terminal commands from within the /examples directory. - On MacOS (with 'parallel' installed, running 1 job at a time) this can be done with: cat Runfile.txt | parallel -j 1 - Further details on CmdStan functions and commands can be found in the online CmdStan User Guide: https://mc-stan.org/docs/2_26/cmdstan-guide/index.html - Results are tabulated in an Output.csv file (with the output file name defined in Runfile.txt)