﻿---
title: Getting started with Python
description: Install the deformable package with pip and run your first simulation from Python.
url: https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/
---

# Getting started with Python – Python SDK – Deformable v0.1.0

The Python SDK brings the Tangerina Deformable engine into your own Python tools. It is the package `deformable`,
pure Python over `libdeformable`, the shared library of the C SDK, and it calls the library with `ctypes`. It has no
third-party dependency, and you need no compiler to install it: the wheel for your platform carries the library.

The package exposes the same scene, mesh tools and render surfaces as the C and Rust SDKs, with Python names and Python
types. What they do, and why, is in the Engine guide, starting with
[How the engine works](https://help.tangerina.io/deformable/v0.1.0/user-guides/engine/how-the-engine-works/); this guide shows how to use them from
Python.

## Requirements

- Python 3.9 or later.
- macOS 11 or later on Apple silicon, Linux x64 with glibc 2.28 or later, or Windows x64.

## Install

Install the package from PyPI with pip, preferably in a virtual environment:

```sh
pip install deformable
```

Or add it to a uv project:

```sh
uv add deformable
```

pip picks the wheel for your platform, such as `deformable-0.1.0-py3-none-macosx_11_0_arm64.whl`. The wheel holds the
package and `libdeformable` inside it, so nothing else needs installing.

## Check the installation

```python
import deformable

print(deformable.__version__, deformable.library_version())
```

```text
0.1.0 0.1.0
```

`deformable.__version__` is the package version. `deformable.library_version()` asks the loaded library for its
version, as `major.minor.patch`. The two match when the package and the library come from the same release.

## Your first simulation

This script builds a closed unit cube, fills it with tetrahedrons, and lets it fall under gravity for one second.
Save it as `falling_cube.py`, then run it with `python falling_cube.py`.

```python
import deformable

# A closed unit cube: 8 corners and 12 outward triangles.
positions = [(x, y, z) for z in (0.0, 1.0) for y in (0.0, 1.0) for x in (0.0, 1.0)]
triangles = [
    (0, 2, 3), (0, 3, 1), (4, 5, 7), (4, 7, 6), (0, 1, 5), (0, 5, 4),
    (2, 6, 7), (2, 7, 3), (0, 4, 6), (0, 6, 2), (1, 3, 7), (1, 7, 5),
]
cage = deformable.TriangleMesh(positions, triangles)

# Fill the cage with tetrahedrons.
mesh = deformable.tetrahedralize(cage, deformable.TetrahedralizeParameters(maximum_edge_length=0.5)).mesh

with deformable.Scene() as scene:
    material = scene.add_material(deformable.MaterialParameters.default())
    cube = scene.add_object(mesh, material)

    # 24 frames per second, 10 substeps per frame. The first call only records the time.
    for frame in range(25):
        scene.step(frame / 24, substeps=10)

    positions = scene.node_positions(cube)
    lowest = min(position.y for position in positions)
    print(f"{len(positions)} nodes, lowest at y = {lowest:.2f}")
```

```text
9 nodes, lowest at y = -4.93
```

Each step does this:

1. `tetrahedralize` turns the closed triangle cage into a `TetrahedralMesh`.
2. `Scene()` creates an empty scene with gravity (0, -9.81, 0). The `with` block frees it at the end.
3. `add_material` returns a material handle, and `add_object` returns an object handle. Both are plain `int` values.
4. `step(time, substeps)` advances the scene to `time`, in seconds. The first call only records the start time.
5. `node_positions` copies the current node positions into a list of `Vector3`.

![A tetrahedral cube is added as an object, then falls further each frame, and its node positions are read after every step.](https://help.tangerina.io/deformable/v0.1.0/images/sdk-first-simulation-loop.svg)

The cube falls about 4.9 units in one second, as free fall predicts. Nothing stops it, because the scene has no
floor. [Scene](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/scene/) shows how to add one.

## License

The package comes with the free 7-day trial: every feature, up to 2,500 tetrahedrons per scene. The first call
that does engine work, such as `tetrahedralize` above, starts the trial with our licensing service, so the computer
must be online that one time. After that it works offline, but a license renews at least once every 7 days of use,
by itself whenever the program runs online. The trial and the license are shared with the plugins and the other SDKs on
the same computer, and they belong to each computer that runs your script: on a colleague's computer, a server or a
render farm node, it starts its own trial and needs its own seat to keep running after 7 days.
[Licensing](https://help.tangerina.io/deformable/v0.1.0/licensing/) has the whole story.

`deformable.license` reads and changes the license state. This script starts the trial, or renews the license, when
that is due, and prints the status line:

```python
import deformable

print(deformable.license.refresh().message)
```

```text
Trial: 7 days left
```

| Function | What it does |
|---|---|
| `status()` | Returns a `LicenseStatus`: the `state`, `days_left`, `tetrahedron_limit` (`None` without a limit), `usable`, `needs_online`, `has_license_key` and the status line `message`. It never goes online. |
| `refresh(timeout=15.0)` | Starts the trial, or renews the license, when that is due. Call it when your tool starts. |
| `activate(license_key, timeout=15.0)` | Activates a license key on this computer, such as `"TGDF-XXXX-XXXX-XXXX"`. Needs internet. |
| `deactivate(timeout=15.0)` | Frees this computer's seat. Needs internet. |
| `set_online_access(allowed)` | With `False`, keeps the script off the network: nothing is sent, and the license works only as far as it works offline. |

The timeouts are in seconds. When the trial or the license does not allow a call, it raises `LicenseError`, a
`DeformableError`, and the message is the status line, such as **Trial ended — Buy license**. See [Types and errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#license-errors).

## How the package finds the library

The package loads the library on the first call that needs it, once per process. It looks in three places, in this
order, and loads the first file it finds:

1. The file named by the `DEFORMABLE_LIBRARY` environment variable. A path that is not a file is skipped.
2. The package folder, `deformable/`, next to `__init__.py`. The wheel carries the library here.
3. `target/release` of the source tree the package sits in, which only a contributor's checkout of the product
   has.

If no place holds the library, the call raises `deformable.LibraryNotFoundError`, a subclass of `OSError`. Its
message lists every path it searched. Importing the package never loads the library, so the import itself does not
fail.

To use another copy of the library, for example one from the [C SDK](https://help.tangerina.io/deformable/v0.1.0/user-guides/c/getting-started/),
point `DEFORMABLE_LIBRARY` at the file:

```sh
export DEFORMABLE_LIBRARY=/opt/deformable/lib/libdeformable.so
```

**Inside Blender.** Blender's bundled Python is newer than 3.9, so the package runs there too. Install it into
Blender's Python, or put it on Blender's module path. You do not need this to use the Blender plugin: the plugin
carries its own copy.

## Conventions

These rules hold for the whole package. [Types and errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/) covers them in full.

- **Errors.** A failed library call raises `DeformableError`, with the status, the message and the indices of the
  element it concerns. An argument the package refuses before it calls the library raises `ValueError` or
  `TypeError`.
- **Arrays.** Inputs can be lists or tuples of groups, flat sequences of numbers, `array.array`, `memoryview` or any
  other buffer. Results are lists of `Vector3` and of index tuples.
- **Handles.** `Scene`, `SurfaceEmbedding` and `CancelFlag` own a library handle. Use them in a `with` block or
  call `close()`. Object and material handles are `int` values that count up from 0.
- **Units.** Lengths cross in host units. Time, forces, gravity, masses and material values are in simulation units.
  The scene's scale converts host lengths to simulation lengths.
- **License.** Engine calls check the trial or license of this computer, and raise `LicenseError` when it does not
  allow them. `deformable.license` reads and changes it.
- **Threads.** Library calls release the global interpreter lock. Calls on one scene run one at a time. Tools,
  embeddings and cancel flags work from several threads at once.

## Next steps

- [How the engine works](https://help.tangerina.io/deformable/v0.1.0/user-guides/engine/how-the-engine-works/): the ideas the plugins and every SDK
  share, explained once in the Engine guide.
- [Scene](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/scene/): materials, objects, driving, glue, stepping and outputs.
- [Tools](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/tools/): the mesh tools that prepare a scene's inputs.
- [Render surfaces](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/render-surfaces/): skin a render mesh on a simulated object.
- [Types and errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/): array forms, handles, errors, threads and units.
- [Python API reference](https://help.tangerina.io/deformable/v0.1.0/api-references/python/overview/): every class, function and field of the package.
