Package: pyhtnorm
htnormThis repo provides a C implementation of a fast and exact sampling algorithm for a
multivariate normal distribution (MVN) truncated on a hyperplane as describedhereThis repo implements the following from the paper:Efficient sampling from a MVN truncated on a hyperplane:Efficient sampling from a MVN with a stuctured precision matrix that is a sum of an invertible matrix and a low rank matrix:Efficient sampling from a MVN with a structured precision and mean:The algorithms implemented have the following practical applications:Topic models when unknown parameters can be interpreted as fractions.Admixture modelsdiscrete graphical modelsSampling from the posterior distribution of an Intrinsic Conditional Autoregressive prioricarSampling from the posterior conditional distributions of various bayesian regression problems.DependenciesA C compiler that implements the C99 standard or laterAn installation ofLAPACK.UsageBuilding a shared library ofhtnormcan be done with the following:# optionally set path to LAPACK shared library$exportLIBS_DIR="some/path/to/lib/"$makelibAfterwards the shared library will be found in alib/directory of the project root,
and the library can be linked dynamically via-lhtnorm.The puplic interface exposes the samplers through the function declarationsinthtn_hyperplane_truncated_mvn(rng_t*rng,constht_config_t*conf,double*out);inthtn_structured_precision_mvn(rng_t*rng,constsp_config_t*conf,double*out);The details of the parameters are documented in ther header files"htnorm.h".Random number generation is done usingPCG64orXoroshiro128plusbitgenerators.
The interface allows using a custom bitgenerator, and the details are documented in the header file"rng.h".Example#include"htnorm.h"intmain(void){...// instantiate a random number generatorrng_t*rng=rng_new_pcg64_seeded(12345);ht_config_tconfig;init_ht_config(&config,...);double*out=...;// array to store the samplesintres=htn_hyperplane_truncated_mvn(rng,&config,out);// res contains a number that indicates whether sampling failed or not....// finally free the RNG pointer at some pointrng_free(rng);...return0;}Python InterfaceDependenciesNumPy >= 1.19.0A high level python interface to the library is also provided. Linux and MacOS users can
install it using wheels via pip (thus not needing to worry about availability of C libraries).
Windows OS is currently not supported.pipinstall-UpyhtnormWheels are not provided for MacOS. To install via pip, one can run the following commands:pipinstall-UpyhtnormAlternatively, one can install it from source using the following shell commands:$gitclonehttps://github.com/zoj613/htnorm.git
$cdhtnorm/
$exportPYHT_LIBS_DIR=<somedirectorywithblasandlapacksharedlibraryfiles># this is optional$pipinstall.Below is an example of how to use htnorm in python to sample from a multivariate
gaussian truncated on the hyperplane(i.e. making sure the sampled values sum to zero). The python
interface is such that the code can be easily integrated into other existing libraries.
Sincev1.0.0, it supports passing anumpy.random.Generatorinstance as a parameter to aid reproducibility.frompyhtnormimporthyperplane_truncated_mvnorm,structured_precision_mvnormimportnumpyasnprng=np.random.default_rng()# generate example inputk1,k2=1000,1temp=rng.random((k1,k1))cov=temp@temp.TG=np.ones((k2,k1))r=np.zeros(k2)mean=rng.random(k1)# passing `random_state` is optional. If the argument is not used, a fresh# random generator state is instantiated internally using system entropy.o=hyperplane_truncated_mvnorm(mean,cov,G,r,random_state=rng)print(o.sum())# verify if sampled values sum to zero# alternatively one can pass an array to store the results inhyperplane_truncated_mvnorm(mean,cov,G,r,out=o)For more information about the function's arguments, refer to its docstring.A pure numpy implementation is demonstrated in thisexample script.R InterfaceOne can also use the package in R. To install, use one the following commands:devtools::install_github("zoj613/htnorm")pak::pkg_install("zoj613/htnorm")Below is an R translation of the above python example:library(htnorm)# make dummy datamean<-rnorm(1000)cov<-matrix(rnorm(1000*1000),ncol=1000)cov<-cov%*%t(cov)G<-matrix(rep(1,1000),ncol=1000)r<-c(0)# initialize the Generator instancerng<-HTNGenerator(seed=12345,gen="pcg64")samples<-rng$hyperplane_truncated_mvnorm(mean,cov,G,r)#verify if sampled values sum to zerosum(samples)# optionally pass a vector to store the results inout<-rep(0,1000)rng$hyperplane_truncated_mvnorm(mean,cov,G,r,out=out)sum(out)#verifyout<-rep(0,1000)eig<-eigen(cov)phi<-eig$vectorsomega<-diag(eig$values)a<-diag(runif(length(mean)))rng$structured_precision_mvnorm(mean,a,phi,omega,a_type="diagonal",out=out)Licensinghtnormis free software made available under the BSD-3 License. For details
see theLICENSEfile.ReferencesCong, Yulai; Chen, Bo; Zhou, Mingyuan. Fast Simulation of Hyperplane-Truncated
Multivariate Normal Distributions. Bayesian Anal. 12 (2017), no. 4, 1017--1037.
doi:10.1214/17-BA1052.Bhattacharya, A., Chakraborty, A., and Mallick, B. K. (2016).
“Fast sampling with Gaussian scale mixture priors in high-dimensional regression.”
Biometrika, 103(4):985.