diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..873af96
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,76 @@
+name: ci
+
+on:
+ pull_request:
+ branches: [main]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: the site builds
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ # Hugo resolves the landingkit module (hugo.toml [module]) with the go
+ # command, at the version go.mod pins.
+ - uses: actions/setup-go@v7
+ with:
+ go-version-file: go.mod
+ cache: false
+ - uses: peaceiris/actions-hugo@v3
+ with:
+ hugo-version: "0.167.0"
+ extended: true
+ - run: hugo --minify
+ # A portal that builds and leaves an organisation out is a portal nobody
+ # notices is incomplete. The list is written here, not read from
+ # hugo.toml: a check that takes its list from the file it checks passes
+ # whatever the file says.
+ - name: every member organisation and repository is on it
+ run: |
+ rc=0
+ for org in go-ndarray go-fft go-numerics go-statistics go-dataframe go-plot go-notebook; do
+ for url in "https://$org.github.io/" "https://$org.github.io/docs/"; do
+ grep -qF "$url" public/index.html \
+ || { echo "::error::$url is not on the page"; rc=1; }
+ done
+ done
+ for repo in go-scikit.github.io brand .github; do
+ grep -qF "go-scikit/$repo" public/index.html \
+ || { echo "::error::go-scikit/$repo is not on the page"; rc=1; }
+ done
+ [ $rc -eq 0 ] && echo "the page names every member organisation, its site and docs, and every repository here"
+ exit $rc
+
+ # The hero shows example/first.md and, under it, example/output.txt: what
+ # running it printed. This runs the notebook again, with the notebook
+ # command and the library versions example/go.mod pins, and fails if the
+ # output differs. Timings ("ran in 41µs") and the "kept" marker of a cached
+ # cell are removed first: they are the only parts that change from run to
+ # run.
+ notebook:
+ name: the notebook prints what the page says
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-go@v7
+ with:
+ go-version-file: example/go.mod
+ cache-dependency-path: example/go.sum
+ - name: Run the notebook
+ working-directory: example
+ env:
+ GOWORK: "off"
+ run: |
+ set -o pipefail
+ go tool notebook run first.md > out.raw
+ sed -E 's/, (ran in [^)]*|kept)\)/)/' out.raw > output.txt
+ - name: The committed output is the one printed
+ run: |
+ if ! git diff --exit-code -- example/output.txt; then
+ echo "::error::example/output.txt differs from what first.md prints: run it again (see README) and commit the output"
+ exit 1
+ fi
diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml
new file mode 100644
index 0000000..0a9c69d
--- /dev/null
+++ b/.github/workflows/hugo.yml
@@ -0,0 +1,96 @@
+# Build + deploy the Hugo site to GitHub Pages on every push to main.
+# Adapted from the official Hugo template at
+# https://gohugo.io/host-and-deploy/host-on-github-pages/.
+
+name: Deploy Hugo site to Pages
+
+on:
+ push:
+ branches: [main]
+ # Build on every pull request too, so a change to the layout, the content or
+ # the Hugo version has to prove the site still builds before it lands.
+ # Without this the workflow ran only on main, which meant a dependency bump
+ # arrived with no signal at all -- its checks read "no checks", which is not
+ # the same thing as green and must not be merged as if it were.
+ pull_request:
+ workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between
+# the run in-progress and latest queued. Don't cancel in-progress
+# runs — we want them to finish before a new build replaces them.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+# The build needs nothing beyond the source and the Pages configuration it
+# reads to compute the base URL. Publishing rights are granted to the deploy
+# job alone, below, so a pull request build cannot replace what is served.
+permissions:
+ contents: read
+ pages: read
+
+env:
+ # Pin Hugo so site builds don't break when a new release ships
+ # incompatible template changes. Bump deliberately, not by
+ # surprise.
+ HUGO_VERSION: 0.135.0
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Install Hugo CLI
+ run: |
+ wget -O hugo.deb "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb"
+ sudo dpkg -i hugo.deb
+
+ - name: Checkout
+ uses: actions/checkout@v7
+ with:
+ submodules: recursive
+
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v6
+
+ # Hugo resolves the landingkit module (hugo.toml [module]) with the go
+ # command, at the version go.mod pins.
+ - name: Setup Go
+ uses: actions/setup-go@v7
+ with:
+ go-version-file: go.mod
+ cache: false
+
+ - name: Build
+ env:
+ HUGO_ENVIRONMENT: production
+ HUGO_ENV: production
+ run: |
+ hugo \
+ --gc \
+ --minify \
+ --baseURL "${{ steps.pages.outputs.base_url }}/"
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v5
+ with:
+ path: ./public
+
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ # Only main publishes. A pull request stops after build above: it has built
+ # the site, which is the whole point of the gate, and it has no business
+ # replacing what is served.
+ if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v5
diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml
new file mode 100644
index 0000000..b03e1b8
--- /dev/null
+++ b/.github/workflows/links.yml
@@ -0,0 +1,43 @@
+name: links
+
+# The landing had a link to https://github.com/go-fileshare/authnd, which is a
+# 404: authnd lives in go-authn. A dead link on a landing page breaks nothing
+# that complains, so every link of the BUILT site is checked (the layouts hold
+# template expressions, not URLs).
+#
+# The checker is `landingkit links`, run at the version the landing's go.mod
+# pins: `go run` without a version inside a module that requires
+# github.com/go-fleettools/landingkit uses that requirement, so Renovate's bump
+# of the partials bumps the checker with them. It probes github.com blob links
+# on raw.githubusercontent.com, because github.com answers a program's request
+# for a blob page with 503 most of the time (see the landingkit README).
+
+on:
+ pull_request:
+ branches: [main]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ links:
+ name: every link and image resolves
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ submodules: recursive
+ - uses: actions/setup-go@v7
+ with:
+ go-version-file: go.mod
+ cache: false
+ - uses: peaceiris/actions-hugo@v3
+ with:
+ hugo-version: "0.167.0"
+ extended: true
+ - run: hugo --minify --destination ./public
+ - name: Check
+ env:
+ GOWORK: "off"
+ run: go run github.com/go-fleettools/landingkit/cmd/landingkit links public
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..256c50e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+public/
+resources/
+.hugo_build.lock
+.DS_Store
diff --git a/README.md b/README.md
index b6f949e..728a42e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,31 @@
# go-scikit.github.io
-The go-scikit portal: the pure-Go scientific stack, one page
+
+The go-scikit portal (Hugo), served at linalg is numpy.linalg, fft is numpy.fft, and random is numpy.random with NumPy's numbers for the same seed."
+ playground = "https://go-ndarray.github.io/playground/"
+[[params.orgs]]
+ name = "go-fft"
+ layer = 0
+ short = "numpy.fft, scipy.fft"
+ lib = "fft"
+ blurb = "The numpy.fft / scipy.fft equivalent: complex and real transforms of any length, N-D, the DCT and DST, single precision, windows, with no dependency on FFTW. AVX2 and AVX-512 kernels on amd64, NEON on arm64, bit-identical to the Go code."
+ playground = "https://go-fft.github.io/playground/"
+[[params.orgs]]
+ name = "go-numerics"
+ layer = 1
+ short = "optimize, integrate, special"
+ lib = "optimize"
+ blurb = "Numerical methods ported statement by statement from their reference algorithms: minimisation, roots, least squares and linear programming (optimize); QUADPACK quadrature and ODE solvers (integrate); gamma, beta, error, Bessel and zeta functions measured against mpmath (special)."
+[[params.orgs]]
+ name = "go-statistics"
+ layer = 1
+ short = "distributions, statistics, tests"
+ lib = "stats"
+ blurb = "32 univariate and 3 multivariate distributions with every method of SciPy's frozen distributions, descriptive statistics with NumPy's 13 quantile methods, and the statistical tests, from t-tests to Shapiro–Wilk and Anderson–Darling."
+[[params.orgs]]
+ name = "go-dataframe"
+ layer = 1
+ short = "labelled tables"
+ lib = "dataframe"
+ blurb = "Series, DataFrame and Index whose numeric columns are go-ndarray arrays: CSV, Arrow and Parquet, group-by, joins, reshaping and time series, giving pandas' answers."
+[[params.orgs]]
+ name = "go-plot"
+ layer = 1
+ short = "figures, SVG and PNG"
+ lib = "plot"
+ blurb = "matplotlib's object model and defaults, figures to SVG and PNG, real TeX in the labels; ticks, colormaps and layout tested equal to matplotlib where they can be equal."
+[[params.orgs]]
+ name = "go-notebook"
+ layer = 2
+ short = "compiled, reactive notebooks"
+ lib = "notebook"
+ blurb = "A notebook is a Markdown file whose go blocks are cells. The kernel compiles it into a real Go program, orders the cells by what they use, and runs only what changed, keeping values across runs."
+
+# The cards of #measured and their count come from this list. Each statement
+# is from the document its link names.
+[[params.claims]]
+ name = "Accuracy against mpmath"
+ what = "go-statistics measures every distribution function in ULPs against mpmath, with SciPy on the same points: at or below SciPy's error in 1473 of 1479 regions, the six exceptions under 4.5 ulp."
+ href = "https://github.com/go-statistics/stats/blob/main/docs/accuracy.md"
+ link = "go-statistics accuracy"
+[[params.claims]]
+ name = "Special functions in ULPs"
+ what = "go-numerics' special functions, about 250 000 points in 419 regions over 62 functions: at or below SciPy's error in 418 regions."
+ href = "https://github.com/go-numerics/special/blob/main/docs/accuracy.md"
+ link = "go-numerics accuracy"
+[[params.claims]]
+ name = "NumPy's numbers, same seed"
+ what = "go-ndarray's random is numpy.random: PCG64, MT19937, Philox, SFC64 and 40 samplers, bit-exact against NumPy 2.5.3 on x86-64, the few ULP-level exceptions listed."
+ href = "https://github.com/go-ndarray/ndarray/blob/main/docs/random.md"
+ link = "go-ndarray random"
+[[params.claims]]
+ name = "SciPy's draws, to the bit"
+ what = "On that generator, go-statistics' draws of 17 distributions, Dirichlet and multinomial are bit-identical to SciPy's; the others are listed with how much they differ."
+ href = "https://github.com/go-statistics/stats/blob/main/docs/rvs-table.md"
+ link = "go-statistics draws"
+[[params.claims]]
+ name = "The reference's path"
+ what = "116 of 124 fixture integrals take SciPy's exact QUADPACK subdivision path, and 110 of 120 solve_ivp runs its exact steps."
+ href = "https://github.com/go-numerics/integrate"
+ link = "go-numerics integrate"
+[[params.claims]]
+ name = "Faster than FFTW, and slower where it is"
+ what = "At v0.27.0 go-fft is faster than FFTW on all 24 rows on Neoverse-N1 and at or above numpy.fft and scipy.fft on all 24 rows on every host measured; the tables include the rows FFTW wins."
+ href = "https://github.com/go-fft/fft/blob/main/BENCHMARKS.md"
+ link = "go-fft benchmarks"
+[[params.claims]]
+ name = "Against NumPy and OpenBLAS"
+ what = "go-ndarray is faster on whole-array reductions and the *Into forms of elementwise operations, and slower on MatMul against 16-thread OpenBLAS from 512²."
+ href = "https://github.com/go-ndarray/ndarray/blob/main/docs/perf.md"
+ link = "go-ndarray performance"
+[[params.claims]]
+ name = "pandas' answers, polars' speed"
+ what = "go-dataframe replays 173 cases recorded from pandas 3.0; polars is faster on most of the operations measured, and the numbers say by how much."
+ href = "https://github.com/go-dataframe/dataframe/blob/main/docs/perf.md"
+ link = "go-dataframe performance"
+[[params.claims]]
+ name = "matplotlib's ticks"
+ what = "go-plot's tick locations, labels and offset text on 408 axes of real figures: every location bit for bit, every label character for character."
+ href = "https://github.com/go-plot/plot/blob/main/docs/design.md"
+ link = "go-plot design"
+
+# Every field below is rendered by layouts/index.html (#repos). A field
+# nothing renders does not stay true.
+[[params.repos]]
+ name = "go-scikit.github.io"
+ kind = "site"
+ href = "https://github.com/go-scikit/go-scikit.github.io"
+ blurb = "This page (Hugo, on the go-fleettools landing kit). The notebook in the hero is run again by CI, which fails if its output changes."
+[[params.repos]]
+ name = "brand"
+ kind = "assets"
+ href = "https://github.com/go-scikit/brand"
+ blurb = "Logos and icons in SVG / PNG / JPG / ICO / ICNS; the mark is the stack, written by a Go program from the list of member organisations."
+[[params.repos]]
+ name = ".github"
+ kind = "profile"
+ href = "https://github.com/go-scikit/.github"
+ blurb = "The organisation profile and the shared Renovate preset."
+
+[params.brand]
+# Generated by go-fleettools/landingkit from static/img/logo.svg: the colours are
+# READ from the logo's gradient, never chosen. Do not add other keys:
+# neutrals (backgrounds, surfaces, greys) belong to the shared sheet.
+# Contrast: base on white 10.55:1, bright on the dark background 7.58:1.
+ base = "#2f3e63"
+ deep = "#1d263c"
+ bright = "#8fa3c8"
+ shadow = "rgba(47,62,99,.7)"
+ glow = "rgba(47,62,99,.6)"
+ wash = "rgba(47,62,99,.10)"
+ washDeep = "rgba(29,38,60,.06)"
+ chipBg = "#f2f4f8"
+ chipBorder = "#dde3ee"
+ chipFg = "#1d263c"
+ chipBgDark = "rgba(143,163,200,.14)"
+ chipBorderDark = "rgba(143,163,200,.32)"
+ chipFgDark = "#c1cce1"
+ statsEnd = "#e4e9f2"
+ bandText = "#edf0f6"
diff --git a/kit.go b/kit.go
new file mode 100644
index 0000000..72ac4fb
--- /dev/null
+++ b/kit.go
@@ -0,0 +1,9 @@
+//go:build tools
+
+// This file never builds. A Hugo site has no Go code, so `go mod tidy` --
+// which Renovate runs after every bump -- would find nothing that uses
+// github.com/go-fleettools/landingkit and delete its requirement from go.mod.
+// Importing it here keeps it. See the landingkit README.
+package site
+
+import _ "github.com/go-fleettools/landingkit"
diff --git a/layouts/index.html b/layouts/index.html
new file mode 100644
index 0000000..328fae6
--- /dev/null
+++ b/layouts/index.html
@@ -0,0 +1,141 @@
+
+
+
made the + hero, and so the whole page, wider than a phone. */}} ++ ++++Science in Go,
+
{{/* The sheet's .accent paints with --grad, base to deep: on a dark page + this logo's dark slate stops would vanish. --accent and --accent-deep + are the same two in light and the bright stop in dark. */}}all the way down.go-scikit is the umbrella over {{ len $orgs }} organisations that together cover what a Python notebook reaches for in NumPy, SciPy, pandas and matplotlib: arrays, FFTs, numerical methods, statistics, labelled tables, figures and notebooks. Pure Go, CGO=0, and each library measured against its Python reference, with the documents that say where it is slower or less accurate.
+ +{{ len $orgs }} organisationsCGO=0 everywhereBSD-3-Clause++ ++{{ $nb }} +$ notebook run first.md +{{ $out }}++ + {{/* The diagram is drawn from params.orgs: layer 2 on top, layer 0 at the + bottom, one box per organisation, as the mark draws it. */}} ++ {{ len $orgs }} organisations — one stack, each with its own site and documentation +{{ range $orgs }}{{ .name }}{{ end }}++ + + How the pieces fit +Arrays at the bottom, notebooks on top.
+go-ndarray's arrays are what the libraries above take and return, and its generator is where their random numbers come from; its
+fftpackage runs on go-fft. go-statistics takes its special functions and optimisers from go-numerics, go-dataframe's numeric columns are go-ndarray arrays and itsdfplotdraws with go-plot, and a go-notebook cell can use all of them.+ {{ range $layer := slice 2 1 0 }} +++ {{ range where $orgs "layer" $layer }} + ++ {{ end }} ++ {{ .name }}
{{ .short }} + + {{ end }} ++ + + The organisations +{{ len $orgs }} organisations, one site each.
+Each organisation has its own landing, documentation and release cycle. The libraries are in the organisations; this page only points at them.
++ {{ range $orgs }} ++++ {{ end }} ++
{{ .name }}
+{{ .blurb | safeHTML }}
+Site → Docs → Source →{{ with .playground }} Playground →{{ end }}
++ + + What is measured +{{ len .Site.Params.claims }} claims, each with its evidence.
+Every figure below is from the library's own documentation, which says how it was measured and against which version of the reference. The references are mpmath, NumPy, SciPy, pandas, matplotlib and FFTW; where a library loses to them, the same documents say so.
++ {{ range .Site.Params.claims }} + + {{ end }} +++ + + Get started +A first notebook, in four commands.
+A notebook is a Markdown file; its
+goblocks are the cells. Put the notebook from the top of this page infirst.md, in a module that requires the libraries it imports, and run it. It prints the quartiles of a thousand normal draws from seed 42: the draws SciPy'snorm.rvs(10, 2, size=1000, random_state=np.random.default_rng(42))makes.+ ++$ go install github.com/go-notebook/notebook/cmd/notebook@latest +$ go mod init example.com/first +$ go get github.com/go-statistics/stats github.com/go-ndarray/ndarray +$ notebook run first.md +{{ $out }} +# notebook html first.md writes first.html +# notebook serve first.md the same, live in the browser, editable+Run it again and every cell is kept: a cell whose code and inputs did not change is not run again, across runs. The go-notebook documentation gives the cell rules; to try the arrays and the transforms without installing anything, the go-ndarray and go-fft playgrounds run them compiled to WebAssembly in the browser.
++ + + Repositories +What is here.
++ {{ range .Site.Params.repos }} ++++ {{ end }} ++{{ .name }}
{{ .kind }}{{ .blurb | safeHTML }}
++ + + + diff --git a/renovate.json b/renovate.json new file mode 100644 index 0000000..123150f --- /dev/null +++ b/renovate.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "extends": ["github>go-scikit/.github"] +} diff --git a/static/favicon.svg b/static/favicon.svg new file mode 100644 index 0000000..bdbe7dc --- /dev/null +++ b/static/favicon.svg @@ -0,0 +1,13 @@ + diff --git a/static/img/logo.svg b/static/img/logo.svg new file mode 100644 index 0000000..bdbe7dc --- /dev/null +++ b/static/img/logo.svg @@ -0,0 +1,13 @@ + +++One stack, {{ len $orgs }} organisations.
+Each library is a
+ {{ partial "icons/github.html" . }}go-scikit on GitHub → +go getaway and none needs cgo. Start from the organisation that matches the question: the arrays, a transform, a solver, a distribution, a table or a figure, then reach the others from a notebook.