Skip to content

Add an end-to-end OLS tutorial#42

Merged
timholy merged 3 commits into
mainfrom
teh/doc-tutorial
May 29, 2026
Merged

Add an end-to-end OLS tutorial#42
timholy merged 3 commits into
mainfrom
teh/doc-tutorial

Conversation

@timholy

@timholy timholy commented May 25, 2026

Copy link
Copy Markdown
Member

A small ordinary-least-squares library wrapped end-to-end as a worked example for the docs: write the Julia source, run build_library to compile and generate wrappers, pip install the resulting package into a clean virtualenv, and call it from Python. The example deliberately covers the full recognized JLWInterop vocabulary in one library — CMatrix{Float64} for the design matrix, CVector{Float64} for response / coefficients / predictions, CString for a report buffer, JLWStatus both as a direct return (predict) and embedded in a result struct (fit's FitResult), and a scalar r_squared.

Lives at examples/ols/; new tutorial page docs/src/tutorial.md sits between Home and Concepts in the docs nav so it acts as the on-ramp.

Known blocker: the example builds end-to-end (build_library succeeds and produces an importable Python package), but the compiled .so cannot yet run its fit entrypoint from a host process. X \ y reaches BLAS through Base.Libc.Libdl.LazyLibrary, whose untyped fields and runtime-hook (jl_libdl_dlopen_func) dispatch put the cold load path outside what juliac --trim=safe's static call-graph analysis can keep alive — the first BLAS call from Python aborts with MethodError: no method matching Base.Libc.Libdl.dlopen(::LazyLibrary, ::UInt32). The tutorial is written as if that works (and once the fix lands it will, with no further changes here); merging it now documents the intended workflow and gives the JLW release docs something to point at.

A small ordinary-least-squares library wrapped end-to-end as a
worked example for the docs: write the Julia source, run
`build_library` to compile and generate wrappers, `pip install` the
resulting package into a clean virtualenv, and call it from Python.
The example deliberately covers the full recognized JLWInterop
vocabulary in one library — `CMatrix{Float64}` for the design
matrix, `CVector{Float64}` for response / coefficients / predictions,
`CString` for a report buffer, `JLWStatus` both as a direct return
(`predict`) and embedded in a result struct (`fit`'s `FitResult`),
and a scalar `r_squared`.

Lives at `examples/ols/`; new tutorial page `docs/src/tutorial.md`
sits between Home and Concepts in the docs nav so it acts as the
on-ramp.

Known blocker: the example *builds* end-to-end (`build_library`
succeeds and produces an importable Python package), but the
compiled `.so` cannot yet *run* its `fit` entrypoint from a host
process. `X \ y` reaches BLAS through `Base.Libc.Libdl.LazyLibrary`,
whose untyped fields and runtime-hook (`jl_libdl_dlopen_func`)
dispatch put the cold load path outside what `juliac --trim=safe`'s
static call-graph analysis can keep alive — the first BLAS call
from Python aborts with `MethodError: no method matching
Base.Libc.Libdl.dlopen(::LazyLibrary, ::UInt32)`. The tutorial is
written as if that works (and once the fix lands it will, with no
further changes here); merging it now documents the intended
workflow and gives the JLW release docs something to point at.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@codecov-commenter

codecov-commenter commented May 25, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.66%. Comparing base (411f734) to head (acabec8).
⚠️ Report is 3 commits behind head on main.

Files with missing lines Patch % Lines
src/build.jl 0.00% 3 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #42      +/-   ##
==========================================
- Coverage   95.01%   94.66%   -0.35%     
==========================================
  Files           5        5              
  Lines         822      825       +3     
==========================================
  Hits          781      781              
- Misses         41       44       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@timholy
timholy merged commit 2e33790 into main May 29, 2026
3 of 4 checks passed
@timholy
timholy deleted the teh/doc-tutorial branch May 29, 2026 13:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants