diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 0000000..6563593 --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,23 @@ +on: [push] + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + - name: Upload + uses: actions/upload-artifact@v1 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf \ No newline at end of file diff --git a/Project.toml b/Project.toml index 024928b..39dd001 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "GaussianRandomFields" uuid = "e4b2fa32-6e09-5554-b718-106ed5adafe9" -version = "2.2.2" +version = "2.2.3" [deps] Arpack = "7d9fca2a-8960-54d3-9f78-7d1dccf2cb97" diff --git a/paper/exponential_grf.jpg b/paper/exponential_grf.jpg new file mode 100644 index 0000000..4d43e78 Binary files /dev/null and b/paper/exponential_grf.jpg differ diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..2306ecb --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,147 @@ +@article{bezanson2017, + title = {Julia: A fresh approach to numerical computing}, + doi = {10.1137/141000671}, + author = {Bezanson, Jeff and Edelman, Alan and Karpinski, Stefan and Shah, Viral B}, + journal = {SIAM review}, + volume = {59}, + number = {1}, + pages = {65--98}, + year = {2017} +} + +@book{bishop2006, + title = {Pattern recognition and machine learning}, + author = {Bishop, Christopher M and Nasrabadi, Nasser M}, + volume = {4}, + number = {4}, + year = {2006} +} + +@article{blondeel2020, + title = {p-refined multilevel quasi-{M}onte {C}arlo for {G}alerkin finite element methods with applications in civil engineering}, + doi = {10.3390/a13050110}, + author = {Blondeel, Philippe and Robbe, Pieterjan and Van hoorickx, C{\'e}dric and Fran{\c{c}}ois, Stijn and Lombaert, Geert and Vandewalle, Stefan}, + journal = {Algorithms}, + volume = {13}, + number = {5}, + pages = {110}, + year = {2020} +} + +@article{chiang2000, + title = {Phase information and the evolution of cosmological density perturbations}, + doi = {10.1046/j.1365-8711.2000.03086.x}, + author = {Chiang, Lung-Yih and Coles, Peter}, + journal = {Monthly Notices of the Royal Astronomical Society}, + volume = {311}, + number = {4}, + pages = {809--824}, + year = {2000} +} + +@book{chiles2012, + title = {Geostatistics: {M}odeling spatial uncertainty}, + author = {Chiles, Jean-Paul and Delfiner, Pierre}, + volume = {713}, + year = {2012}, + doi = {10.1016/s0098-3004(00)00063-7}, + publisher = {John Wiley \& Sons} +} + +@inproceedings{cui2018, + title = {Uncertainty quantification of electronic and photonic ICs with non-{G}aussian correlated process variations}, + doi = {10.1145/3240765.3240860}, + author = {Cui, Chunfeng and Zhang, Zheng}, + booktitle = {Proceedings of the International Conference on Computer-Aided Design}, + pages = {1--8}, + year = {2018} +} + +@article{GSTools, + author = {M\"uller, S. and Sch\"uler, L. and Zech, A. and He{\ss}e, F.}, + title = {\texttt{GSTools} v1.3: a toolbox for geostatistical modelling in {P}ython}, + journal = {Geoscientific Model Development}, + volume = {15}, + year = {2022}, + number = {7}, + pages = {3161--3182}, + url = {https://gmd.copernicus.org/articles/15/3161/2022/}, + doi = {10.5194/gmd-15-3161-2022} +} + +@book{lord2014, + title = {An introduction to computational stochastic PDEs}, + author = {Lord, Gabriel J and Powell, Catherine E and Shardlow, Tony}, + volume = {50}, + year = {2014}, + publisher = {Cambridge University Press} +} + +@book{montero2015, + title = {Spatial and spatio-temporal geostatistical modeling and kriging}, + author = {Montero, Jos{\'e}-Mar{\'\i}a and Fern{\'a}ndez-Avil{\'e}s, Gema and Mateu, Jorge}, + year = {2015}, + publisher = {John Wiley \& Sons} +} + +@article{pirot2015, + title = {Influence of conceptual model uncertainty on contaminant transport forecasting in braided river aquifers}, + doi = {10.1016/j.jhydrol.2015.07.036}, + author = {Pirot, Guillaume and Renard, Philippe and Huber, Emanuel and Straubhaar, Julien and Huggenberger, Peter}, + journal = {Journal of Hydrology}, + volume = {531}, + pages = {124--141}, + year = {2015} +} + +@article{PlotsJL, + url = {https://openresearchsoftware.metajnl.com/articles/10.5334/jors.431/}, + doi = {10.5334/jors.431}, + author = {Christ, Simon and Schwabeneder, Daniel and Rackauckas, Christopher and Borregaard, Michael Krabbe and Breloff, Thomas}, + keywords = {Graphics (cs.GR), FOS: Computer and information sciences, FOS: Computer and information sciences, I.3.3}, + title = {Plots.jl -- {A} user extendable plotting API for the {J}ulia programming language}, + publisher = {Journal of Open Research Software}, + year = {2023}, + copyright = {Creative Commons Attribution 4.0 International} +} + +@misc{randomfields, + author = {Schlather, M}, + title = {RandomFields}, + year = {2022}, + publisher = {CRAN}, + journal = {CRAN repository}, + url = {https://cran.r-project.org/web/packages/RandomFields/index.html} +} + +@article{robbe2021, + title = {Enhanced multi-index {M}onte {C}arlo by means of multiple semicoarsened multigrid for anisotropic diffusion problems}, + doi = {10.1002/nla.2281}, + author = {Robbe, Pieterjan and Nuyens, Dirk and Vandewalle, Stefan}, + journal = {Numerical Linear Algebra with Applications}, + volume = {28}, + number = {3}, + pages = {e2281}, + year = {2021} +} + +@article{stephenson2006, + title = {Adaptive Markov random fields for example-based super-resolution of faces}, + doi = {10.1155/asp/2006/31062}, + author = {Stephenson, Todd A and Chen, Tsuhan}, + journal = {EURASIP Journal on Advances in Signal Processing}, + volume = {2006}, + pages = {1--11}, + year = {2006} +} + +@article{wu2023, + title = {Physics-embedded inverse analysis with algorithmic differentiation for the earth’s subsurface}, + doi = {10.1038/s41598-022-26898-1}, + author = {Wu, Hao and Greer, Sarah Y and O’Malley, Daniel}, + journal = {Scientific Reports}, + volume = {13}, + number = {1}, + pages = {718}, + year = {2023} +} \ No newline at end of file diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..7d6a93e --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,48 @@ +--- +title: 'GaussianRandomFields.jl: A Julia package to generate and sample from Gaussian random fields' +tags: + - Julia + - random fields + - uncertainty quantification + - statistics +authors: + - name: Pieterjan Robbe + orcid: 0000-0002-6254-8245 + affiliation: "1" +affiliations: + - name: KU Leuven, Belgium + index: 1 +date: 27 May 2023 +bibliography: paper.bib +--- + +# Summary + +Random fields are used to represent spatially-varying uncertainty, and are commonly used as training data in uncertainty quantification and machine learning applications. GaussianRandomFields.jl is a Julia [@bezanson2017] software package to generate and sample from Gaussian random fields. It offers support for well-known covariance functions, such as Gaussian, exponential and Matérn covariances [@bishop2006; @chiles2012; @montero2015], as well as user-defined covariance structures defined on arbitrary domains. The package implements most common methods to generate samples from these random fields, including the Cholesky factorization, the Karhunen-Loève expansion, and the circulant embedding method [@lord2014]. GaussianRandomFields.jl makes use of [Plots.jl](https://github.com/JuliaPlots/Plots.jl) [@PlotsJL] to quickly visualize samples of the random fields. + +# Statement of need + +Random fields are used by scientists to describe complex patterns and structures emerging in nature. They provide a statistical tool for describing a vast amount of different structures found in various applications such as electronics [@cui2018], geostatistics [@pirot2015], machine learning [@stephenson2006] and cosmology [@chiang2000]. Random fields can be viewed as an extension from random variables to random functions, in the sense that the random field takes random values at each point in the domain where it is defined. Gaussian random fields are particularly attractive, because they only require two parameters to be fully specified: a mean value and a covariance function. GaussianRandomFields.jl provides Julia implementations of Gaussian random fields with stationary separable and non-separable isotropic and anisotropic covariance functions. It has been used in a number of recent works, including [@blondeel2020], [@robbe2021] and [@wu2023]. + +Other packages for Gaussian random field generation are available in R [@randomfields] and Python [@GSTools]. GaussianRandomFields.jl offers a native Julia implementation. As such, it benefits from the performance advantage of Julia, see [@bezanson2017], and provides a convenient unified API for different covariance functions by leveraging multiple dispatch. A particular example are the covariance functions from [KernelFunctions.jl](https://github.com/JuliaGaussianProcesses/KernelFunctions.jl), which can easily be linked to the Gaussian random field generators implemented in this package. + +# Usage + +The full API of GaussianRandomFields.jl is described in detail in the [documentation](https://pieterjanrobbe.github.io/GaussianRandomFields.jl/stable/). We also provide a [tutorial](https://pieterjanrobbe.github.io/GaussianRandomFields.jl/stable/tutorial) with various examples detailing how to define, sample from, and visualize Gaussian random fields. The following example is an excerpt from the tutorial. We refer to \autoref{fig:samples} for an illustration. + +```julia +using GaussianRandomFields, Plots + +cov = CovarianceFunction(2, Exponential(.5)) +pts = range(0, stop=1, length=1001) +grf = GaussianRandomField(cov, CirculantEmbedding(), pts, pts, minpadding=2001) +heatmap(grf) +``` + +![Three realizations of a two-dimensional Gaussian random field with exponential covariance function.\label{fig:samples}](exponential_grf.jpg) + +# Acknowledgements + +The author acknowledges the help of David Widmann implementing a dimension-independent variant of the circulant embedding method using `@generated` functions. + +# References