# Getting started

## Create a project

Create a project with [uv](<https://docs.astral.sh/uv/>) and Git:

```bash
uvx --from 'git+ssh://git@github.com/fieldextension/ren-onboarding.git@main' ren init my-project
cd my-project
uv run main.py
uv run pytest
```

The starter includes a CPU example in `main.py` and a test in `test_main.py`. The decrypted result should be close to `[1.0, 1.5, 2.0]`. Edit `main.py` to change the computation. Its parameters are unsuitable for production security.

Omit `my-project`, or use `.`, to initialize the current directory. The directory must be empty except for existing `.git` metadata.

`ren init` initializes Git only when the directory is outside an existing repository and leaves the files uncommitted.

## Development tools

Test, lint, format, and type-check:

```bash
uv run pytest
uv run ruff check
uv run ruff format
uv run ty check
```

## Update Ren

To update Ren to the latest `main`:

```bash
uv sync -P ren
```

## Run the examples

Save each Python example below as `example.py` in your generated project, then run it on the CPU:

```bash
DEV=python uv run example.py
```

## First CKKS computation

The example uses `CKKSParams.python_test()`, a small, non-secure parameter set intended for local examples and tests.

```python
import numpy as np

from ren.schemes.ckks import CKKSParams, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()

values = np.array([0.25, 0.5, 0.75, 1.0])

with ctx:
    pt = encode(values, msg_bound=1.0)
    ct = encrypt(pt)
    result = ct + 1
    level = result.level
    decoded = decode(decrypt(result), length=len(values))

print("level:", level)
print("slots:", [round(z.real, 3) for z in decoded])
```

```
level: 5
slots: [1.25, 1.5, 1.75, 2.0]
```

The example decodes the first four slots: `[0.25, 0.5, 0.75, 1.0]` becomes `[1.25, 1.5, 1.75, 2.0]`. Sequence encoding pads the remaining CKKS slots with zeros, and scalar constants apply to every slot, including that padded tail. The printed level stays at the fresh-encryption level because adding an integer scalar does not rescale.

- `msg_bound` is public metadata. It must be chosen independently of secret values.
- Many CKKS properties, such as `level`, require an active `CKKSContext`.

## First polynomial graph

`Poly` operations are lazy. They build an IR graph and execute when you realize or export the value.

```python
from ren.poly import Poly
from ren.ring import RingSpec


ring = RingSpec(n=8, moduli=(17, 97))

a = Poly([1, 2, 3, 4, 0, 0, 0, 0], ring)
b = Poly([4, 3, 2, 1, 0, 0, 0, 0], ring)

result = (a + b) * 2

print("coefficients:", result.tolist())
print("node:", result.node)
```

```
coefficients: [10, 10, 10, 10, 0, 0, 0, 0]
node:  0  UNIQUE       0
 1  DEVICE       python
 2  BUFFER       [0, 1] size=8
 3  TO_RNS       [2]
 4  UNIQUE       1
 5  BUFFER       [4, 1] size=8
 6  TO_RNS       [5]
 7  ADD          [3, 6]
 8  CONST        [1] 2
 9  AS_RING      [8] coeff (n=8 q=<11b> moduli=2 dtype=u64)
10  MUL          [7, 9]

====== Summary ======
UNIQUE             2
BUFFER             2
TO_RNS             2
DEVICE             1
ADD                1
CONST              1
AS_RING            1
MUL                1
```

The printed `node` trace is the graph Ren will schedule. The inputs are buffers, the arithmetic stays symbolic, and the scalar `2` appears as a constant node.

## First JIT replay

`ren.jit` works on arguments and return values that contain `Poly` values directly or inside ordinary containers and dataclasses. CKKS `Ciphertext` and `Plaintext` objects work because they carry `Poly` fields inside dataclasses.

```python
import ren
from ren.schemes.ckks import CKKSParams, Ciphertext, decode, decrypt, encode, encrypt, keygen


params = CKKSParams.python_test()
keys = keygen(params)
ctx = keys.context()
captures = 0


@ren.jit
def affine(x: Ciphertext) -> Ciphertext:
    global captures
    captures += 1
    return (x + 1) * 0.5


with ctx:
    x1 = encrypt(encode([1.0, 2.0, 3.0], msg_bound=4))
    y1 = affine(x1)
    print("captures after first call:", captures)
    print("first output:", [round(z.real, 3) for z in decode(decrypt(y1), length=3)])

    x2 = encrypt(encode([2.0, 3.0, 4.0], msg_bound=5))
    y2 = affine(x2)
    print("captures after second call:", captures)
    print("second output:", [round(z.real, 3) for z in decode(decrypt(y2), length=3)])
```

```
captures after first call: 1
first output: [1.0, 1.5, 2.0]
captures after second call: 1
second output: [1.5, 2.0, 2.5]
```

The first call records the operations in `affine`. The second runs them on the new ciphertext, producing a different result while the capture counter stays at one. The counter increment runs only during capture.

The replay plan can be reused because the ciphertext components have the same ring, size, dtype, device, and domain.

## Next

- Read [Build a CKKS circuit](<https://ren-docs.pages.dev/tutorials/ckks-circuit/index.md>) for the first reusable encrypted computation.
- Read [CKKS workflow](<https://ren-docs.pages.dev/ckks/index.md>) for the practical encrypted-computation workflow.
- Read [CKKS concepts](<https://ren-docs.pages.dev/concepts/ckks-model/index.md>) for levels, scales, message bounds, and keys.
- Read [Engine overview](<https://ren-docs.pages.dev/engine/overview/index.md>) for the core `Poly -> Node -> schedule -> backend` model.
- Read [Polynomial engine](<https://ren-docs.pages.dev/engine/polynomial/index.md>) for ring, RNS, domain, node, constant, and view semantics.
- Read [Execution pipeline](<https://ren-docs.pages.dev/engine/execution/index.md>) to connect lazy user code to scheduled backend work.
- Read [Scheduling](<https://ren-docs.pages.dev/engine/scheduling/index.md>) when you need to understand why a graph turns into a particular set of kernels.
- Read [Runtime](<https://ren-docs.pages.dev/engine/runtime/index.md>) when you need to reason about memory planning, backends, copies, or JIT replay.
