You are viewing the documentation for Deformable v0.2.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:
pip install deformableOr add it to a uv project:
uv add deformablepip 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
import deformable
print(deformable.__version__, deformable.library_version())0.1.0 0.1.0deformable.__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.
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}")9 nodes, lowest at y = -4.93Each step does this:
tetrahedralizeturns the closed triangle cage into aTetrahedralMesh.Scene()creates an empty scene with gravity (0, -9.81, 0). Thewithblock frees it at the end.add_materialreturns a material handle, andadd_objectreturns an object handle. Both are plainintvalues.step(time, substeps)advances the scene totime, in seconds. The first call only records the start time.node_positionscopies the current node positions into a list ofVector3.
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 both licenses. It comes with the free 7-day Standard 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 Standard
license renews at least once every 7 days of use, by itself whenever the program runs online. The Standard trial and
license are shared with the plugins and the other SDKs on the same computer. An application you ship to others uses a
Developer license instead: it activates the Developer key at every start, offline, as its first Deformable call, before
status and refresh. Licensing has the whole story.
deformable.license reads and changes the license state. This script starts the Standard trial, or renews the
Standard license, when that is due, and prints the status line:
import deformable
print(deformable.license.refresh().message)Standard trial: 7 days left| Function | What it does |
|---|---|
status() |
Returns a License: the state, days_, tetrahedron_ (None without a limit), usable, needs_, has_ and the status line message. It never goes online. |
refresh(timeout=15.0) |
Starts the Standard trial, or renews the Standard license, when that is due. On a Standard license, call it when your tool starts. A program on a Developer license never needs it: it activates its key first. |
activate(license_ |
Turns a license key on. A Standard key, such as "TGDF-XXXX-XXXX-XXXX", is activated on this computer and needs internet. A Developer key, "TGDF-<payload>.<signature>", is checked offline and holds for this run of the program, so call it at every start. |
deactivate(timeout=15.0) |
Frees this computer’s Standard seat. Needs internet. |
set_ |
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 license does not allow a call, it raises LicenseError, a
DeformableError, and the message is the status line, such as Standard trial ended — Buy license. See
Types and errors.
The Standard trial and the Standard license belong to each computer that runs the script. On a colleague’s computer, a server or a render farm node, it starts its own Standard trial and needs its own seat to keep running after 7 days. To ship the engine inside an application you give to others, you need a Developer license: contact us. Your application 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:
- The file named by the
DEFORMABLE_LIBRARYenvironment variable. A path that is not a file is skipped. - The package folder,
deformable/, next to__init__.py. The wheel carries the library here. target/releaseof 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:
export DEFORMABLE_LIBRARY=/opt/deformable/lib/libdeformable.soInside 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 raisesValueErrororTypeError. - Arrays. Inputs can be lists or tuples of groups, flat sequences of numbers,
array.array,memoryviewor any other buffer. Results are lists ofVector3and of index tuples. - Handles.
Scene,SurfaceEmbeddingandCancelFlagown a library handle. Use them in awithblock or callclose(). Object and material handles areintvalues 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
LicenseErrorwhen it does not allow them.deformable.licensereads 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: 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.