Quickstart#

Import `opynsim`#

After installing OPynSim, it may be imported into Python code like this:

import opynsim as opyn

This convention allows access to the opynsim Python module with a short, recognizable, prefix (opyn.), which we use extensively in this documentation.

Read an `osim` File#

ModelSpecification is a central part of the opynsim API. It’s a high-level model specification object that can be used to build and customize the resulting Model's behavior.

One way to create a ModelSpecification is to read it from an .osim file using read_osim(). This means OPynSim can read complex specifications built using visual tools like OpenSim Creator.

import opynsim as opyn
import opynsim.config
import pathlib

# (optional): Add a geometry directory to the search path, so that
#             OPynSim can find shared mesh files.
opyn.config.append_search_path("/some/geometry/directory")

# Read an `.osim` file into a `ModelSpecification`.
model_specification = opyn.read_osim("arm26.osim")

# `pathlib.Path`s are also supported.
model_specification2 = opyn.read_osim(pathlib.Path("/some/path/to/arm26.osim"))

Note

The remainder of the documentation uses generators from the opynsim.examples module (e.g. examples.pendulum_specification()) to create ModelSpecifications.

This is because it’s easier to copy + paste Python code that uses generated examples. However, you can always exchange an example ModelSpecification for one loaded via read_osim().

Compile a Specification into a Model#

Once a ModelSpecification has been prepared, it can be used to compile a Model using the ModelSpecification.compile() method:

import opynsim as opyn
import opynsim.examples

# alternatively: model_specification = opyn.read_osim("your.osim")
model_specification = opyn.examples.double_pendulum_specification()

# ... if necessary, edit the `ModelSpecification`, and then...

model = model_specification.compile()  # builds the model from the specification

Create and Realize an Initial State of the Model#

Model.initial_state() creates an initial ModelState for a model. This is the state of the model that you would see if loading it in a visualizer without loading states externally:

import opynsim as opyn
import opynsim.examples

model_specification = opyn.examples.double_pendulum_specification()
model = model_specification.compile()

model_state = model.initial_state()              # Produce an initial state of the model.
model.realize(model_state, opyn.STAGE_DYNAMICS)  # Realize the state to a specific simulation stage.

Once you have a ModelState, you can the manipulate and inspect it according to your modelling requirements. The above example uses Model.realize() to realize state to a later ModelStateStage, which can be necessary to read certain computed outputs from the state.

A shorthand version of the above would be:

import opynsim as opyn
import opynsim.examples

model = opyn.examples.double_pendulum_model()  # or `*_specification().compile()`
model_state = model.initial_state(realized_to=opyn.STAGE_DYNAMICS)

Visualize the Model in a State#

OPynSim supports User Interfaces, which can be useful for visualizing and interacting with its datastructures.

The opynsim.ui module provides high-level functions, such as ui.show_model_in_state(), which visualizes a Model in a single ModelState. The state should be realized to ModelStateStage.REPORT to ensure the state contains all necessary information the UI may read:

import opynsim as opyn
import opynsim.examples
import opynsim.ui

model = opyn.examples.double_pendulum_model()
model_state = model.initial_state(
    realized_to=opyn.STAGE_REPORT  # Required for rendering/UI
)

# Shows `model` in `state` in an interactive window.
opyn.ui.show_model_in_state(model, model_state)

Render Visualization to an Image File#

The OPynSim Graphics API provides utilities for rendering OPynSim’s datastructures to images (graphics.Texture2D). This can be useful for automating tasks like creating custom plots or creating images/videos of models.

The API includes high-level functions, such as graphics.render_model_in_state(), which returns a graphics.Texture2D - a class that stores rendered pixel data. The example below renders an Model + ModelState to a texture and then uses Pillow to write the pixel data to a PNG file:

import opynsim as opyn
import opynsim.examples
import opynsim.graphics
from PIL import Image  # from `Pillow` package

# Create/import a `Model` + `ModelState`.
model = opyn.examples.double_pendulum_model()
model_state = model.initial_state(realized_to=opyn.STAGE_REPORT)

# Render the `Model` + `ModelState` to a `Texture2D` (image).
texture_2d = opyn.graphics.render_model_in_state(model, model_state)

# Copy the texture's pixels into a `PIL.Image` object.
image = Image.fromarray(texture_2d.pixels_rgba32(), mode="RGBA")

# Save the `PIL.Image` as a PNG file.
image.save("render_output.png")

Quickstart

Contents