pyopensim 4.5.2.0

PyOpenSim: Portable Python bindings for OpenSim

PyOpenSim: Unofficial Portable Python bindings for OpenSim, which is an open source software system for biomechanical modeling, simulation and analysis.

Key Features

• Portable: Self-contained Python wheels with bundled OpenSim libraries
• Type Hints: Comprehensive .pyi stub files for excellent IDE support and type checking
• Cross-Platform: Native support for Linux, macOS, and Windows
• Official Bindings: Uses OpenSim's native SWIG bindings for full API compatibility

Installation

Install directly from PyPI:

pip install pyopensim

No additional setup required! All OpenSim dependencies are bundled in the wheel.

Why pyopensim?

While the OpenSim team provide an excellent conda package, pyopensim offers complementary benefits for specific use cases:

• Enhanced IDE Support: Comprehensive type hints (.pyi stubs) provide excellent autocomplete, type checking, and documentation in modern IDEs
• Wheel Distribution: Self-contained wheels make it easy to bundle OpenSim with your applications without requiring users to manage conda environments
• Flexible Deployment: Works well in environments where conda isn't preferred (Docker containers, CI/CD pipelines)

Quick Start

import pyopensim as osim

# Check versions
print(f"PyOpenSim version: {osim.__version__}")
print(f"OpenSim core version: {osim.__opensim_version__}")

# Create a simple model
model = osim.Model()
model.setName("MyModel")

# Add a body
body = osim.Body("body", 1.0, osim.Vec3(0), osim.Inertia(1))
model.addComponent(body)

# Build and initialize
state = model.initSystem()
print(f"Model has {model.getNumBodies()} bodies")

Versioning

PyOpenSim uses a 4-digit versioning scheme that directly tracks the OpenSim core version:

• Version format: <MAJOR>.<MINOR>.<PATCH>.<BUILD>

  • Example: 4.5.2.0 - Matches OpenSim 4.5.2 exactly
  • Example: 4.5.2.1 - First Python binding fix for OpenSim 4.5.2
  • Example: 4.5.2.2 - Second Python binding fix for OpenSim 4.5.2

• What the version tells you:

  • The first 3 digits (e.g., 4.5.2) match the bundled OpenSim core version exactly
  • The 4th digit indicates Python binding-specific fixes or improvements
  • A build number of 0 means the bindings match OpenSim without additional changes

This makes it easy to know which OpenSim version you're using:

import pyopensim as osim
print(osim.__version__)          # e.g., "4.5.2.0" or "4.5.2.1"
print(osim.__opensim_version__)  # e.g., "4.5.2" (always the core version)

PyPI Distribution

pyopensim is automatically built and deployed to PyPI using:

• Automated Builds: GitHub Actions CI/CD builds wheels for all platforms
• cibuildwheel: Ensures compatibility across Python versions and platforms
• Bundled Libraries: All OpenSim dependencies are included in the wheels
• Version Management: Semantic versioning automatically aligned with OpenSim releases
• Automated Tests: Automated testing ensures each release works correctly (work in progress)

This provides an alternative distribution method that complements the official OpenSim library.

Contributing

We welcome contributions of all kinds! Whether you're fixing bugs, improving type stubs, or enhancing documentation, your help is appreciated.

Contributing Guidelines - Complete guide for contributors

Key areas where you can help:

• Type Stub Improvements: Enhance IDE support and type checking
• Documentation: Add examples and usage guides
• Testing: Cross-platform validation and edge cases
• Bug Reports: Help us improve reliability

Relationship to OpenSim

pyopensim is an unofficial python package that is built on top of the official OpenSim project:

• Same API: Identical to the official OpenSim Python bindings
• Same Functionality: Full access to all OpenSim features and capabilities
• Regular Updates: Tracks OpenSim releases to provide latest features

To use the official OpenSim conda package, checkout this package.

Development

This project builds OpenSim from source to create self-contained Python wheels.

Linux/macOS:

# Clone the repository
git clone https://github.com/neurobionics/pyopensim.git
cd pyopensim

# Build OpenSim and dependencies
make setup

# Build Python wheels
make build

Windows:

# Clone the repository
git clone https://github.com/neurobionics/pyopensim.git
cd pyopensim

# Build OpenSim and dependencies
.\make.ps1 setup

# Build Python wheels
.\make.ps1 build

See WINDOWS.md for detailed Windows build instructions.

The build process includes:

• Compiling OpenSim's C++ libraries and dependencies
• Generating SWIG Python bindings
• Creating comprehensive type stubs for IDE support
• Bundling everything into portable wheels

License

This project is licensed under Apache License 2.0. OpenSim is licensed under the Apache License 2.0. See the OpenSim license for details.

Issues

If you encounter any issues or have questions regarding pyopensim, please open an issue here.

Community & Support

• Report Issues - Bug reports and feature requests
• Discussions - Questions and community support
• OpenSim Documentation - Official OpenSim resources
• OpenSim Website - OpenSim project