Skip to content

Readme scaladays #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benikm91 merged 5 commits into from
Oct 23, 2026
Merged

Readme scaladays #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9f8a456
improve example in README
marcelluethi Sep 29, 2026
6817b44
Restructure README around the ScalaDays talk
benikm91 Oct 22, 2026
8a9f89c
Add feedback Marcel
benikm91 Oct 23, 2026
64819bb
Update the Why. Layout.
benikm91 Oct 23, 2026
851e269
Furhter clean up the Why
benikm91 Oct 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 68 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,78 @@
# DimWit - Tensor programming with wit

> Programming is the art of telling another human being what one wants the computer to do.
>
> Donald Knuth
<table>
<tr>
<td width="40%" align="center">
<img src="assets/dimwit-logo.svg" alt="DimWit — Tensor programming with wit" width="300">
</td>
<td>
<p><i>“Programming is the art of telling another human being what one wants the computer to do.”</i><br>— Donald Knuth</p>
<p><b>Vision:</b> A system for writing numerical and machine learning programs that puts human understanding first. While programming, the compiler should help us to keep concepts separate and sharpen our thinking about the problem.</p>
<p>▶ Watch the <a href="https://www.youtube.com/watch?v=2ZwGhCWXN5g">ScalaDays 2026 talk</a>.</p>
</td>
</tr>
</table>

## Why DimWit?

Why yet another tensor library? With untyped tensors, the meaning of each axis lives only in the programmer's head. DimWit puts it into the types, e.g. `Tensor2[Batch, Feature, Float32]`, without sacrificing runtime speed:

- **Easier to understand.** Concepts become types, so the compiler helps keep them apart, sharpening the thinking about the problem.
- **Easier to review.** The meaning of each axis is part of the code, streamlining code reviews, which matters all the more in the era of AI-generated code.
- **Names are a shared vocabulary.** Axes like `Batch` or `Feature` name the concepts of the domain, so the code reads close to the theory behind it. They become a shared vocabulary for your team and your AI agents, whether you discuss code, review it or prompt for it.
- **Fast.** DimWit is on par with JAX: under `jit`, a function is traced once and the compiled XLA program runs without Scala in the loop. [GPT-2 in DimWit](https://github.com/dimwit-dev/deepwit/tree/main/examples/src/main/scala/deepwit/examples/gpt) (124M parameters, trained from scratch on 10B tokens) trains as fast as in plain JAX.

<p align="center">
<img src="assets/dimwit-logo.svg" alt="DimWit — Tensor programming with wit" width="360">
</p>
## Example

A minimal example of what named dimensions add to a tensor program, next to the same program in JAX:

## Vision
<table>
<tr><th>DimWit</th><th>JAX</th></tr>
<tr>
<td>

We want to create a system for writing numerical and machine learning programs that puts human understanding first. While programming, the compiler should help us to keep concepts separate and sharpen our thinking about the problem.
```scala
// The axis names are the shared vocabulary
trait Batch derives Label
trait Feature derives Label
trait Output derives Label

## Why?
// f has a strict signature: mapping a feature vector to an output vector
def f(x: Tensor1[Feature, Float32]): Tensor1[Output, Float32] = ...

AI coding agents and modern numerical libraries, such as Jax, Pytorch or Tensorflow, make it ever easier to write numerical and machine learning programs. Yet understanding remains as difficult as ever. Untyped code,
opaque tensor operations and a focus on performance instead of clarity often obscure the concepts underlying the code.
// Tensor types carry meaning and are tracked by the compiler
val X: Tensor2[Batch, Feature, Float32] = ...
val Y: Tensor2[Batch, Output, Float32] =
X.vmap(Axis[Batch])(f) // the axis by name, not position
```

With *DimWit* we want to change this by
- allowing to express concepts clearly and on a high level
- leveraging the type system to enable the compiler to help us keep
concepts separate and check correctness.
</td>
<td>

## How?
```python

DimWit uses the power of the Scala 3 type system to encode tensor dimensions as types. It combines this with a high-level API inspired by
JAX and einops, and efficient implementations of tensor operations using JAX as a backend.

## Example

```scala
import dimwit.*

// Labels are simply Scala types
trait Batch derives Label
trait Feature derives Label

// Create a 2D tensor with shape (3, 2), labeled with Batch and Feature
val t = Tensor(
Shape(Axis[Batch] -> 3, Axis[Feature] -> 2),
).fromArray(
Array(
1.0f, 2.0f,
3.0f, 4.0f,
5.0f, 6.0f
)
)

// Function to normalize a single feature vector
def normalize(x: Tensor1[Feature, Float32]) : Tensor1[Feature, Float32] =
(x -! x.mean) /! x.std

// Apply the normalization function across the Batch dimension
val normalized: Tensor2[Batch, Feature, Float32] =
t.vmap(Axis[Batch])(normalize)

def f(x: Tensor) -> Tensor: ...


X: Tensor = ...
Y: Tensor = (
jax.vmap(f, in_axes=0)(X))
```

</td>
</tr>
</table>

In DimWit, the names state the intent of the code; in JAX, the reader has to infer it from axis positions.


See our [quickstart guide](docs/quickstart.md) for a more detailed introduction to the core concepts and API and
check out the [examples](examples/src/main/scala).
check out the [examples](examples/src/main/scala).

## Using DimWit as a Library

Expand Down Expand Up @@ -122,11 +136,19 @@ Alternatively, you can configure the Python environment manually using these env
- `DIMWIT_PYTHON_LIBRARY` — path to the Python shared library (find it with `python3 -c "import ctypes.util; print(ctypes.util.find_library('python3'))"`)
- `DIMWIT_SKIP_SYNC` — set to `true` to skip uv environment sync on startup

## Status
## Scope

Like JAX, DimWit is a library for fast numerical programming: tensors, automatic differentiation, `vmap`, `jit` and random numbers.
Everything else is built on top of it:

**Early but functional.** DimWit successfully runs complex models including GPT-2 (see [example](https://github.com/dimwit-dev/deepwit/tree/main/examples/src/main/scala/deepwit/examples/gpt)). The core concepts are stable, but the API is still evolving.
| Project | Description |
|---|---|
| [DeepWit](https://github.com/dimwit-dev/deepwit) | Functional deep learning library providing core modules and examples. |
| [WitDraw](https://github.com/dimwit-dev/witdraw) | Experimental library for probabilistic programming. |

## Status

**Not production-ready** - expect breaking changes.
**Ready to use.** The core concepts are stable and the API is maturing, but breaking changes may still happen until 1.0.

## Contributing

Expand Down
125 changes: 82 additions & 43 deletions mdocs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,95 @@
# DimWit - Tensor programming with wit

> Programming is the art of telling another human being what one wants the computer to do.
>
> Donald Knuth
<table>
<tr>
<td width="40%" align="center">
<img src="assets/dimwit-logo.svg" alt="DimWit — Tensor programming with wit" width="300">
</td>
<td>
<p><i>“Programming is the art of telling another human being what one wants the computer to do.”</i><br>— Donald Knuth</p>
<p><b>Vision:</b> A system for writing numerical and machine learning programs that puts human understanding first. While programming, the compiler should help us to keep concepts separate and sharpen our thinking about the problem.</p>
<p>▶ Watch the <a href="https://www.youtube.com/watch?v=2ZwGhCWXN5g">ScalaDays 2026 talk</a>.</p>
</td>
</tr>
</table>

## Why DimWit?

Why yet another tensor library? With untyped tensors, the meaning of each axis lives only in the programmer's head. DimWit puts it into the types, e.g. `Tensor2[Batch, Feature, Float32]`, without sacrificing runtime speed:

- **Easier to understand.** Concepts become types, so the compiler helps keep them apart, sharpening the thinking about the problem.
- **Easier to review.** The meaning of each axis is part of the code, streamlining code reviews, which matters all the more in the era of AI-generated code.
- **Names are a shared vocabulary.** Axes like `Batch` or `Feature` name the concepts of the domain, so the code reads close to the theory behind it. They become a shared vocabulary for your team and your AI agents, whether you discuss code, review it or prompt for it.
- **Fast.** DimWit is on par with JAX: under `jit`, a function is traced once and the compiled XLA program runs without Scala in the loop. [GPT-2 in DimWit](https://github.com/dimwit-dev/deepwit/tree/main/examples/src/main/scala/deepwit/examples/gpt) (124M parameters, trained from scratch on 10B tokens) trains as fast as in plain JAX.

<p align="center">
<img src="assets/dimwit-logo.svg" alt="DimWit — Tensor programming with wit" width="360">
</p>
## Example

@marcelluethi marcelluethi Oct 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is nice. I like the side by side view


A minimal example of what named dimensions add to a tensor program, next to the same program in JAX:

## Vision

@marcelluethi marcelluethi Oct 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep the vision label. I think it is important to know where we want to go and where not.

<table>
<tr><th>DimWit</th><th>JAX</th></tr>
<tr>
<td>

We want to create a system for writing numerical and machine learning programs that puts human understanding first. While programming, the compiler should help us to keep concepts separate and sharpen our thinking about the problem.
```scala
// The axis names are the shared vocabulary
trait Batch derives Label
trait Feature derives Label
trait Output derives Label

## Why?
// f has a strict signature: mapping a feature vector to an output vector
def f(x: Tensor1[Feature, Float32]): Tensor1[Output, Float32] = ...

AI coding agents and modern numerical libraries, such as Jax, Pytorch or Tensorflow, make it ever easier to write numerical and machine learning programs. Yet understanding remains as difficult as ever. Untyped code,
opaque tensor operations and a focus on performance instead of clarity often obscure the concepts underlying the code.
// Tensor types carry meaning and are tracked by the compiler
val X: Tensor2[Batch, Feature, Float32] = ...
val Y: Tensor2[Batch, Output, Float32] =
X.vmap(Axis[Batch])(f) // the axis by name, not position
```

With *DimWit* we want to change this by
- allowing to express concepts clearly and on a high level
- leveraging the type system to enable the compiler to help us keep
concepts separate and check correctness.
</td>
<td>

## How?
```python

DimWit uses the power of the Scala 3 type system to encode tensor dimensions as types. It combines this with a high-level API inspired by
JAX and einops, and efficient implementations of tensor operations using JAX as a backend.

## Example

```scala mdoc:silent



def f(x: Tensor) -> Tensor: ...


X: Tensor = ...
Y: Tensor = (
jax.vmap(f, in_axes=0)(X))
```

</td>
</tr>
</table>

In DimWit, the names state the intent of the code; in JAX, the reader has to infer it from axis positions.

```scala mdoc:invisible
// Compiles the DimWit example above
import dimwit.*

// Labels are simply Scala types
trait Batch derives Label
trait Feature derives Label
trait Output derives Label

val A: Tensor2[Feature, Output, Float32] = Tensor2(Axis[Feature], Axis[Output]).fromArray(Array(Array(0f, -1f, 0f), Array(1f, 2f, 2f)))

// Create a 2D tensor with shape (3, 2), labeled with Batch and Feature
val t = Tensor(
Shape(Axis[Batch] -> 3, Axis[Feature] -> 2),
).fromArray(
Array(
1.0f, 2.0f,
3.0f, 4.0f,
5.0f, 6.0f
)
)

// Function to normalize a single feature vector
def normalize(x: Tensor1[Feature, Float32]) : Tensor1[Feature, Float32] =
(x -! x.mean) /! x.std

// Apply the normalization function across the Batch dimension
val normalized: Tensor2[Batch, Feature, Float32] =
t.vmap(Axis[Batch])(normalize)
def f(x: Tensor1[Feature, Float32]): Tensor1[Output, Float32] =
x.dot(Axis[Feature])(A)

val X: Tensor2[Batch, Feature, Float32] = Tensor2(Axis[Batch], Axis[Feature]).fromArray(Array(Array(1f, 2f), Array(3f, 4f), Array(5f, 6f)))
val Y: Tensor2[Batch, Output, Float32] =
X.vmap(Axis[Batch])(f)
```

See our [quickstart guide](docs/quickstart.md) for a more detailed introduction to the core concepts and API and
check out the [examples](examples/src/main/scala).
check out the [examples](examples/src/main/scala).

## Using DimWit as a Library

Expand Down Expand Up @@ -122,11 +153,19 @@ Alternatively, you can configure the Python environment manually using these env
- `DIMWIT_PYTHON_LIBRARY` — path to the Python shared library (find it with `python3 -c "import ctypes.util; print(ctypes.util.find_library('python3'))"`)
- `DIMWIT_SKIP_SYNC` — set to `true` to skip uv environment sync on startup

## Status
## Scope

Like JAX, DimWit is a library for fast numerical programming: tensors, automatic differentiation, `vmap`, `jit` and random numbers.
Everything else is built on top of it:

**Early but functional.** DimWit successfully runs complex models including GPT-2 (see [example](https://github.com/dimwit-dev/deepwit/tree/main/examples/src/main/scala/deepwit/examples/gpt)). The core concepts are stable, but the API is still evolving.
| Project | Description |
|---|---|
| [DeepWit](https://github.com/dimwit-dev/deepwit) | Functional deep learning library providing core modules and examples. |
| [WitDraw](https://github.com/dimwit-dev/witdraw) | Experimental library for probabilistic programming. |

## Status

**Not production-ready** - expect breaking changes.
**Ready to use.** The core concepts are stable and the API is maturing, but breaking changes may still happen until 1.0.

## Contributing

Expand Down
Loading