You are viewing the documentation for Deformable v0.3.1, an older version. Read the latest, v0.9.0

Python SDK

Getting started with Python

Install the deformable package with pip and run your first simulation from Python.

On this page

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; 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.
tetrahedral mesh add object each frame: step, then read node positions

The cube falls about 4.9 units in one second, as free fall predicts. Nothing stops it, because the scene has no floor. Scene shows how to add one.

License

The package works with all three licenses. Without a key, it runs under the Free license, forever: every feature, up to 2,500 tetrahedrons per scene, with no account and no internet, and nothing is sent. A Standard license lifts the limit on your device: activate its key once, online, and the library renews it by itself while the script runs online, at least once every 7 days. It is shared with the plugins and the other SDKs on the same device. An app you ship to others uses a Developer license instead: it activates the Developer key at every start, offline, as its first Deformable call, before any engine call. Licensing has the whole story.

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

python
import deformable

print(deformable.license.refresh().message)
text
Free license: up to 2,500 tetrahedrons per scene — Buy license
Function What it does
status() Returns a LicenseStatus: the state, days_left (of a Developer trial), tetrahedron_limit (2500 under the Free license, None without a limit), has_license_key and the status line message. It never goes online.
refresh(timeout=15.0) Renews the Standard license when that is due. On a Standard license, call it when your tool starts. Without a key, and under a Developer license, it contacts nothing.
activate(license_key, timeout=15.0) Turns a license key on. A Standard key, such as "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx", is activated on this device and needs internet. A Developer key, "tgdfp-<payload hex>-<signature hex>", is checked offline and holds for this run of the program, so call it at every start.
deactivate(timeout=15.0) Forgets the Standard license on this device at once, even offline, and frees its seat when the device is online.
set_online_access(allowed) With False, keeps the script off the network: nothing is sent, and the Standard license runs only as long as it runs offline.

The state is a deformable.LicenseState, such as FREE_LICENSE, STANDARD_LICENSE or DEVELOPER_LICENSE. NEEDS_ONLINE (a Standard license that needs a renewal) and DEVELOPER_TRIAL_ENDED run under the Free license, with its limit.

The timeouts are in seconds. Under the Free license, Scene.add_object raises TetrahedronLimitExceededError, a LicenseError, for an object that would take the scene past the limit, with a message such as Free license: this would simulate 3,120 tetrahedrons; the limit is 2,500 per scene. See Types and errors.

The Standard license belongs to each device that runs the script. On a colleague’s device, a server or a render farm node, the script runs under the Free license, up to 2,500 tetrahedrons per scene, unless that device has its own seat. To ship the engine inside an app you give to others, you need a Developer license: your app then activates its key at every start, offline, and its users need no activation, network or seat. See Developer license.

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, 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 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. Under the Free license, a scene simulates up to 2,500 tetrahedrons, and Scene.add_object raises TetrahedronLimitExceededError for an object past the limit. deformable.license reads and changes the license.
  • 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: the ideas the plugins and every SDK share, explained once in the Engine guide.
  • Scene: materials, objects, driving, glue, stepping and outputs.
  • Tools: the mesh tools that prepare a scene’s inputs.
  • Render surfaces: skin a render mesh on a simulated object.
  • Types and errors: array forms, handles, errors, threads and units.
  • Python API reference: every class, function and field of the package.