libKriging gallery

Worked examples of libKriging, one per use case: every model class (Kriging with its noise models and approximate fit methods, NestedKriging, WarpKriging, MLPKriging) on classical test problems, explained, plotted and tabulated, next to the packages it is usually compared with.

Each example is also a validation: what it shows is checked against a reference (finite differences, a fit from scratch, the exact model an approximation converges to, another kriging package at the same hyperparameters, the other bindings). CI runs every notebook against the development head of libKriging and of its bindings (and weekly against the releases), saves it with its outputs, and turns the checks into a report: the gallery is libKriging's end-to-end acceptance test.

Every notebook starts with its idea, its reference and its tags, and ends with a summary of its checks; error-level checks fail the run, warn-level ones are reported (see Checks and statuses).

Gallery site: https://libkriging.github.io/gallery/: one card per notebook (first figure, title, idea, tags: language, Kriging class, kernel, objective, method, noise/nugget, warping, aggregation, compared packages; status of its checks), tag filters; a card opens its notebook, executed by the last CI run on main, in nbviewer (Python cards also link to Colab and Binder). Built by tools/site.py, published on the gh-pages branch.

The examples

executed: the notebook as run by the last CI run on main against libKriging master, with its outputs (a zip of the executed-master-<notebook> artifact through nightly.link, which serves the last artifact of a branch at a stable URL; all runs on main keep them 90 days; all of a run at once: executed-notebooks-master, and the aggregated report: report-master). open in: the executed notebook of the site, run in a free hosted service (see below), or read in nbviewer. The notebook column links to its source in src/: the notebooks themselves are generated and executed by CI only, never committed.

One binding per use case: Python, the most complete binding, unless the reference belongs to another language (DiceKriging and RobustGaSP in R, STK in Octave, GaussianProcesses.jl in Julia); the cross-binding notebooks check that every binding gives the same numbers as Python, for every class and fit method.

Kriging: the basics

notebook	binding	kriging type	what it shows	validated against	executed	open in
update-simulate_Kriging_python	python	Kriging	the workflow on 1D to 6D functions: fit, predict, conditional paths, update with new data, update_simulate, in pictures	fit from scratch, Monte Carlo moments	zip	Colab · Binder
kernels-trends-interpolation_Kriging_python	python	Kriging	choosing a kernel and a trend: 4 × 4 combinations on 8 functions, interpolation, predicted covariance and derivatives	finite differences, Q² floors	zip	Colab · Binder
objectives-LL-LOO-LMP-gradients_Kriging_python	python	Kriging	choosing the estimation criterion (LL, LOO, LMP), its profile around θ̂, multistart	finite differences, explicit leave-one-out refits	zip	Colab · Binder
high-dimension-normalize-screening_Kriging_python	python	Kriging	6 to 20 inputs in physical units: normalize, reading the fitted θ to screen inputs (Welch)	explicit rescaling, known active inputs	zip	Colab · Binder
save-load-pickle-copy-accessors_Kriging_python	python	Kriging	saving, loading, pickling, copying a model; reading its settings back	the original model (to 1e-12)	zip	Colab · Binder
sklearn-estimators_Kriging_python	python	Kriging	libKriging inside scikit-learn: Pipeline, GridSearchCV over kernels, cross_val_score, sample_y	the native class	zip	Colab · Binder

Noisy observations

notebook	binding	kriging type	what it shows	validated against	executed	open in
noisy-data_Kriging-nugget-noise_python	python	Kriging with noise="nugget" or variances	estimated nugget vs known noise variances, replicates, calibrated intervals on the noise-free function	true noise, replicate averaging, interpolating fit	zip	Colab · Binder

Large datasets

notebook	binding	kriging type	what it shows	validated against	executed	open in
large-n_Kriging-vecchia-nystrom_python	python	Kriging with method="vecchia(m)" / "nystrom(k)"	n up to 5000: Vecchia and Nyström fits, their convergence to the exact model as m and k grow, subsetOfData	exact model (limits m = n − 1, k = n), exact fit	zip	Colab · Binder
aggregations-large-n_NestedKriging_python	python	NestedKriging	splitting a design into groups: NK, PoE, gPoE, BCM, rBCM, from 1 group to 32	exact predictor (limit: 1 group), exact fit	zip	Colab · Binder

Non-stationary, categorical and ordinal inputs

notebook	binding	kriging type	what it shows	validated against	executed	open in
warpings-categorical-ordinal_WarpKriging_python	python	WarpKriging	input warpings (affine, boxcox, kumaraswamy, knots, neural_mono), categorical and ordinal inputs	plain Kriging (accuracy, NLPD), none warping = Kriging	zip	Colab · Binder

Deep kernels

notebook	binding	kriging type	what it shows	validated against	executed	open in
deep-kernel-projected-branin_MLPKriging_python	python	MLPKriging	an MLP feature map finding the 2D structure of a 10D function; activations, multistart	plain Kriging	zip	Colab · Binder

libKriging and other kriging packages

notebook	binding	kriging type	what it shows	validated against	executed	open in
vs-sklearn-SMT-OpenTURNS-GPy_Kriging_python	python	Kriging	same hyperparameters → same numbers, then default fits on 10 functions (accuracy, calibration, cost)	scikit-learn, SMT, OpenTURNS, GPy	zip	Colab · Binder
vs-DiceKriging-RobustGaSP_Kriging_R	R	Kriging	rlibkriging next to the R references: equality at fixed hyperparameters, default fits	DiceKriging, RobustGaSP	zip	nbviewer
vs-STK_Kriging_octave	octave	Kriging	mLibKriging next to STK: equality at fixed hyperparameters (Gaussian kernel), default fits	STK	zip	nbviewer
vs-GaussianProcesses_Kriging_julia	julia	Kriging	JLibKriging next to GaussianProcesses.jl: default fits	GaussianProcesses.jl	zip	nbviewer

Validation only

notebook	binding	kriging type	what it shows	validated against	executed	open in
test-functions-reference-values_no-model_python	python	—	the 21 test functions used throughout, plotted and checked	published optima / values	zip	Colab · Binder
robustness-invalid-inputs_Kriging_python	python	Kriging	invalid and degenerate inputs, ill-conditioning, units, extrapolation, prediction cost in q	equivariance identities, O(q) cost	zip	Colab · Binder
cross-binding-reference_all-classes_python	python	all classes	the same data and options in every binding, every class and fit method: the Python values	R, Octave, Julia (report)	zip	Colab · Binder
cross-binding_all-classes_R	R	all classes	the R side of the cross-binding protocol	Python (report)	zip	nbviewer
cross-binding_all-classes_octave	octave	all classes	the Octave side	Python (report)	zip	nbviewer
cross-binding_all-classes_julia	julia	all classes	the Julia side	Python (report)	zip	nbviewer

Notebooks are named <theme>_<kriging type>_<binding>. Those comparing with another package install it themselves, in their first cells (pip, CRAN, Pkg.add, or a clone of STK); a package that cannot be installed is reported (warn-level) and its comparison skipped. Test functions: tools/python/gallery.py (section 1), after the Virtual Library of Simulation Experiments (Surjanovic & Bingham). The notebook sources are in src/; everything else is under tools/ (helpers, notebook generation, installation of the bindings, CI scripts, site generator, known issues, baselines), the shared datasets under data/, the Binder environment under .binder/.

Running a notebook in Colab or Binder

The open in links (and the cards of the site) open the executed notebook of the gh-pages branch, outputs of the last CI run included; re-running it in a free hosted service uses the released pylibkriging (from PyPI), not libKriging master as CI does: a feature not released yet is reported as SKIP. The first code cell of each Python notebook (tools/notebook_setup.py, a no-op in this repository) clones the repository for its datasets and helpers and installs pylibkriging when missing; the notebooks that compare with other packages install them themselves.

• Colab: PyPI has pylibkriging wheels for CPython 3.10 to 3.12 only, and Colab's default runtime has used Python 3.13 since August-September 2026: choose Runtime > Change runtime version > 2026.07 (Python 3.12) before running, otherwise the setup cell stops with this message.
• Binder: the environment of .binder/ (Python 3.12, pylibkriging), copied to gh-pages by the site generator; the first start builds the image, which takes a few minutes.

Not offered for the R, Octave and Julia notebooks (nbviewer instead, read only): Octave is not available on Colab, and the installation of rlibkriging (compiled from CRAN sources) and of JLibKriging.jl (which compiles libKriging) on these services has not been checked.

Checks and statuses

Each notebook records its checks in a suite named after the notebook, and writes results/<notebook>.checks.csv and results/<notebook>.metrics.csv, with the helpers of one file per language, loaded by the notebook (not installed):

	Python	R	Octave	Julia
file	tools/python/gallery.py	tools/R/gallery.R	tools/octave/gallery.m	tools/julia/gallery.jl
loaded by	import gallery (path set by the setup cell)	source("tools/R/gallery.R")	source("tools/octave/gallery.m")	include("tools/julia/gallery.jl")
a suite	suite = gallery.Suite(name)	s <- suite(name)	s = suite(name)	s = Suite(name)
a check	suite.check(name, ok, ...)	check(s, name, ok, ...)	s = check(s, name, ok, ...)	check!(s, name, ok; ...)
usual checks	suite.check_close, check_less, check_greater, check_between, check_true, check_finite, check_runs, check_skip, check_raises	check_close(s, ...), ...	s = check_close(s, ...), ... (no check_runs: try)	check_close!(s, ...), ..., check_runs!(s, name) do ... end
metrics	suite.metric(case, package, q2=...)	metric(s, case, package, q2 = ...)	s = metric(s, case, package, "q2", v)	metric!(s, case, package; q2=...)
end of notebook	suite.summary(), suite.finalize()	suite_summary(s), suite_finalize(s)	suite_summary(s), suite_finalize(s)	suite_summary(s), suite_finalize!(s)
data, errors	gallery.read_data, metrics.rmse, metrics.q2, metrics.nlpd, ...	read_data, rmse, q2, nlpd, coverage	read_data, rmse, q2	read_data, rmse, q2

The Python file also holds the test functions (TESTS), the designs (design.lhs, design.dataset), what the installed pylibkriging offers (compat.has) and the persistence checks (persistence.check), used by the Python notebooks only.

status	meaning	fails CI
PASS
FAIL	an error-level check failed: a correctness property (gradient vs finite differences, update vs fit from scratch, equality with another package at fixed hyperparameters, ...) or an accuracy floor	yes
WARN	a warn-level check failed: performance comparison, optimizer behaviour, judgement thresholds	no
KNOWN	a failing check (of either level) listed in tools/known_issues.csv, with the issue	no
SKIP	feature absent from the installed version (release channel)	no

tools/report.py aggregates all results: status per notebook, failures, warnings, known issues still present, known issues that now pass (to be removed from the list), cross-binding consistency against Python, and metric drifts against tools/baseline/.

Running locally

From the repository root (the notebooks' paths are relative to it; generated notebooks land there, ignored by git):

git clone --recurse-submodules https://github.com/libKriging/libKriging ../libKriging   # for a master build
tools/install/python.sh master ../libKriging      # or: tools/install/python.sh release
tools/install/r.sh master ~/Rlib ../libKriging    # then R_LIBS_USER=~/Rlib
tools/install/octave.sh ../libKriging ~/mlib      # then OCTAVE_PATH=~/mlib
tools/install/julia.sh ../libKriging
python tools/py2nb.py src/update-simulate_Kriging_python.py   # or no argument: every source
python tools/run_notebooks.py --inplace update-simulate_Kriging_python.ipynb
python tools/report.py --expect python
mkdir -p executed && cp *.ipynb executed/
python tools/site.py --notebooks executed --results results --out _site   # then open _site/index.html

The scripts of tools/install/ are the ones CI runs; each says what it needs (BLAS/LAPACK headers, Octave, R, Julia).

Editing notebooks

A notebook exists only as a plain-text source in src/ (cells separated by # %% / # %% [markdown], or % %% in Octave), so that reviews are plain diffs. tools/py2nb.py turns it into a notebook (Python ones get the setup cell of tools/notebook_setup.py); CI does so in each notebook job, executes it, and archives and publishes the executed notebook (see The examples).

python tools/py2nb.py               # every notebook of src/, at the repository root
python tools/py2nb.py --check       # CI: every source valid (name, title, idea, reference, tags, suite)

A new example is a new source in src/ named <theme>_<kriging type>_<binding>, with its suite named the same, a first markdown cell holding its title (# <Language> · <class> — <theme>) and an Idea, a Reference and a Tags paragraph, then plots and tables of its results, its checks, a final ## Summary cell, and a line in the tables above (CI checks that every source is linked from this README); CI picks it up automatically. Tags are key: value, value groups separated by ·, with the keys class (required), kernel, trend, objective, method, noise, warping, aggregation, compared to, topic; the language comes from the file extension. They become the tags and filters of the site.

Shared datasets (data/, used by the cross-binding notebooks of every language) are written once by tools/make_data.py and committed: the files are the reference.

CI

.github/workflows/notebooks.yml, on push, pull request, weekly, on demand (libkriging_ref, libkriging_repo, channels inputs) and on a repository_dispatch of type libkriging-updated (sent by libKriging after a merge, with the commit in client_payload.ref):

• master channel (every event): libKriging built from source at the requested ref, with every binding from the same checkout: Python wheel, R package (bindings/R), Octave mex, JLibKriging.jl;
• release channel (weekly, or on demand): pylibkriging from PyPI, rlibkriging from CRAN, mLibKriging built from the last release tag (the published binaries target another Octave version than Ubuntu's); no Julia.

One build job per binding and channel, then one job per notebook, each uploading its executed notebook and its results as the artifact executed-<channel>-<notebook>; then one report per channel (job summary, report-<channel> artifact with the report, all CSV results and a refreshed baseline, and executed-notebooks-<channel> with all the executed notebooks); then the site job builds the gallery site from the executed notebooks of the master channel (artifact site, for a preview, on every run) and, on main with libKriging/libKriging as source, force-pushes it as the single commit of the gh-pages branch (contents: write for this job only). The initial tools/baseline/ files come from a local run (Python notebooks only, 4-core container); to refresh them, commit the new-baseline/ files of a trusted CI run.