Owl hides three array implementations behind one interface, and tests at one job

Three array implementations behind one interface

The code structure section describes an unusual design, and it is the most useful part of the page.

There is a base array type, which is Owl's fundamental numerical data structure, built on top of both OCaml and C functions and libraries. There is a second array type called the base system architecture, which shares the same set of interfaces and is implemented in pure OCaml. And there is a third, which wraps either of the first two.

Because the interfaces are shared, code written against one type runs against all three. That is the point of the design, and it is what makes the rest of the library portable across implementations rather than tied to one.

On top of those three sit the advanced modules: algorithmic differentiation, optimisation and neural networks. All three work with any of the array types, which means the automatic differentiation and the optimiser do not care whether the arithmetic underneath is C, pure OCaml, or a graph.

It also explains why the library is written in OCaml at all rather than being a binding layer over a C library: the array type is an interface, and OCaml is where the interface lives.

The pure OCaml array is documented as slower and less complete

The page does not oversell the portable implementation. It says the pure OCaml version is sufficient for daily use for normal computing, and then adds two clauses in the same sentence: it does not implement some of the advanced functions that the main array type has, and its performance is much slower.

That is the right way to document it, and it has a direct consequence for anyone choosing an implementation. There is no feature-flag-only difference; there is a functional difference and a large constant-factor difference, both acknowledged. Code written against the shared interface can run on the fast type, but code that relies on an advanced function will fail on the portable one at the point of use rather than at the point of selection.

The feature list on the same page reinforces the boundary. Visualisation is not built in at all; it is delegated to an external package. The core is mathematical functions, integration, interpolation and extrapolation, statistics and probability, arrays with slicing and broadcasting, linear algebra, differential equations, Fourier transforms, automatic differentiation, optimisation, regression, neural networks, natural language processing and dataframes.

The graph layer is described as an older tensor style

The third array type is the interesting one to read about, because the page names its model explicitly. It supports symbolic style computing in the style of a first-generation tensor framework, and it exists to make building a computation graph and optimising a computation easier.

Its construction is the mechanism worth noting: it is built by wrapping one of the other two array types, and whichever one it wraps is what actually executes the computation. So the graph layer is not a fourth way to store numbers. It is a layer above an executor, and the executor can be either the C-backed array or the portable one.

That is a cleaner separation than most frameworks manage, and it has an obvious consequence: the performance of a graph-based program is the performance of the array underneath it, so the same portable-versus-fast decision resurfaces at every level.

The neural network and language processing support is where the optional computation graph optimisation applies, so the graph type is optional in the sense that nothing in the page requires it for the linear algebra or statistics work.

The release target names four packages and the tree holds three

The build file ends with a release recipe, and it is more detailed than most. It sets a package list of four names, then runs the install target first, with a comment explaining why: the package distribution steps rely on the base package being installed.

It installs a release tool, tags, builds a distribution archive and publishes, then for each of the four packages it generates an opam file and submits it.

Now compare that against the repository. There are three opam files at the root: one for the base package, one for the main package, one for the top-level package. The fourth name in the release list has no file in the tree.

That is a gap that only shows up when you try to cut a release. It may well be generated during the build rather than committed, but if it is, nothing in the page says so, and a contributor following the documented process will hit it at the worst possible moment.

Tests run at one job and the docs target overwrites a tracked directory

Two build targets tell you how this project is actually worked on.

The test target runs the suite through the build tool with a single job and no buffering, filtered to one package. One job means serialised execution, which is a deliberate choice for a numerical library where tests bind native libraries and a parallel run would be a source of flakiness, and it is also why a full run is slow.

The documentation target builds the docs and then copies the generated output over the documentation directory in the repository. So the docs directory is a build artefact that is also under version control, regenerated by a make target rather than authored in place. That is convenient until two people build at once.

There is also a formatting target that promotes automatic fixes without asking, and a cleanup target that deletes every merlin directory in the tree, which is housekeeping for an editor integration that OCaml has since replaced. The cleanup rule is a small piece of evidence about how long the repository has been in service.

The container clones the default branch, so the image has no version

The container build is short and has one decision worth arguing with. It clones the project repository at build time, from its default branch, with no tag and no commit reference:

RUN cd /root && git clone https://github.com/owlbarn/owl.git

Everything after that is a straight build and install from whatever that clone contained at the moment the image was built. There is no package installation step, so the version of the library inside a published image is whatever the branch tip was, and an image rebuilt a month later is a different library under the same name.

The base is also an untagged distribution image, which for a numerical library means the compiler and system maths libraries move underneath you.

On top of that, the images are published under a personal account rather than the project organisation, while the clone in the build comes from the organisation's repository. So the artefact that users pull and the artefact that is built are maintained in two different places under two different names.

The optimisation flags that would break portability are present and switched off

The container file contains a commented-out block of compiler flags, and it is worth reading precisely because of what it contains. It sets optimisation level, fast maths, loop unrolling, and architecture-specific tuning including a flag that compiles for the build machine's own processor, alongside a numeric library define and a strict-aliasing relaxation.

All of it is commented out. That is the right default, and it is also an admission that these flags were once in play. An architecture-specific flag inside a container image is the classic portability bug: the image builds for whichever machine runs the build and then fails, or silently miscompiles, elsewhere.

Two other lines are commented out for related reasons. One would set the library path where compiled stubs live, and one would set the shell path to include the versioned toolchain directory. Leaving them disabled is what makes the image work across versions, at the cost of requiring the environment to be set up at run time.

The rest of the file disables the package manager's sandbox and pipes an unconditional yes into its initialisation, which is normal for a container that installs from a package index and is worth knowing about before you trust the layer.

Two approvals per pull request, and a stated policy of limited resources

The contribution section is unusually specific about process. Every change goes through a pull request, and each one needs approval from at least two key developers in the team. Team members own the domains they claim and are responsible both for issues in that domain and for fixing problems caused by accepting work in it. Large changes need an issue opened first so the community and team can discuss them. And anything that falls outside a member's claimed domain gets a best-effort response with no guaranteed timing.

The mission section states the constraint behind those rules in one sentence: the project aims to keep the library stable while actively maintaining it, using the limited time and human resource available.

Put together, they describe a volunteer project with a formal review gate, which is a good thing for users and a real constraint on contributors. The community lives on a language forum and a chat channel, and the page is explicit that support is voluntary and given as time permits.

One last detail about where the project's own story lives: the page sends readers to an external encyclopedia page for the history of the project. The authoritative history of a library is not in the library.

Editorial conclusion

This is a mature library with an unusually honest design document and an equally honest statement about its own resources. The architecture is the reason to look: one interface over three array implementations means portable code, and the page is candid that the portable one is slower and missing some functions, which is more useful than a single implementation with an implicit performance cliff. Two operational things to check. The release cadence has drifted, with the newest tagged version from December 2024 and commits continuing into 2026, so decide whether you are tracking a branch or a version. And the packaging surface is uneven, with the release target naming four distributions while three opam files are in the tree. For contributors, the review rule of two key developers plus domain ownership is a real constraint on a volunteer project, and the project says so itself when it notes that it aims to keep the library stable with the limited time and human resource it has.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. owlbarn/owl on GitHub
4. README
5. Releases