CmdStan-RUS Bilayer Demonstration Files and Code

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

本仓库包含了复现论文"A New Elastic Characterization Method for Anisotropic Bilayer Specimens via Bayesian Resonant Ultrasound Spectroscopy"（作者B.R. Goodlet、B. Bales与T.M. Pollock）于2021年发表于《Ultrasonics》的研究成果所需的全部必要输入文件，用于实现CmdStan-RUS双层代码对虚拟双层样本"VB-4"与实验双层样本"EB-1"的双似然、优化加拉普拉斯近似（Laplace approximation）拟合。

该.stan构建文件包含详尽注释，涵盖：模块与函数说明、2组实验的输入数据（exp_1为裸基底，exp_2为双层试样）、参数定义、取值范围与单位、转换后参数（坐标）、先验分布，以及"正态"与"对数正态"两种噪声模型的代码。
Datafile-vb4.dat与Datafile-eb1.dat分别提供了exp_1与exp_2的输入数据。

注：本类模型（尤其是双层模型）的计算精度设置为可生成"出版级质量"的拟合结果，此类拟合可能需要32GB以上的运行内存，且运行时长超过24小时。
若要在内存较小的计算机上测试代码，可尝试使用低精度拟合，设置参数为：P_exp1 = 10，PX_exp2 = 12，PY_exp2 = 12，PZ_sub_exp2 = 1，PZ_coat_exp2 = 0（若拟合完成，请注意由于P值不足，参数估计结果可能存在偏差）。
若代码在向output.csv文件写入首次迭代前崩溃，可能的原因包括：(i) 超出了计算机的内存上限；或(ii) 若你提高了拟合的计算精度，则可能超出了代码的计算极限。

Runfile-vb4.txt与Runfile-eb1.txt各包含3组命令：前两组先执行优化（使用有限内存BFGS（Limited-memory Broyden-Fletcher-Goldfarb-Shanno, LBFGS）算法），随后执行拉普拉斯近似；第三组执行完整的哈密顿蒙特卡洛（Hamiltonian Monte Carlo, HMC）推断（使用无回旋采样器（No-U-Turn Sampler, NUTS）算法）。
- 第一组命令未指定初始条件，因此将生成随机初始条件，随后执行1000次优化迭代与1000次拉普拉斯抽样。
- 第二组命令指定使用init-vb4.dat作为初始条件，随后执行1000次优化迭代与1000次拉普拉斯抽样。
- 第三组命令使用哈密顿蒙特卡洛对后验分布进行抽样：先执行250次预热迭代（这是成功实现HMC自动调优的最低要求），随后执行500次抽样迭代（用于计算后验分布）。

请注意，相较于后验的拉普拉斯近似，后验的哈密顿蒙特卡洛抽样可能需要10至100倍的前向模型评估次数，出版级质量的拟合甚至需要连续计算30天以上。
init-vb4.dat详细说明了初始条件的指定方式：可对.stan构建文件中定义的任意或全部参数指定初始条件，转换后参数的初始条件将被忽略。