Contributing¶

Thank you for your interest in contributing to Soft Robot Models in jaX (SoRoMoX)! This guide will help you get started.

This page is the canonical contributor workflow. The top-level CONTRIBUTING.md is a compact entry point for repository visitors.

Development Setup¶

1. Fork and Clone¶

git clone https://github.com/YOUR_USERNAME/soromox.git
cd soromox

2. Install Development Dependencies¶

pip install -e ".[dev,docs,examples]"

With uv, create the project environment from the lock file:

uv sync --extra dev --extra docs --extra examples

Add task-specific extras when needed: rendering for all visualization backends, rl for reinforcement-learning workflows, and paper_results for the complete paper reproduction environment.

3. Set Up Pre-commit Hooks¶

pre-commit install

Development Workflow¶

1. Create a Branch¶

git checkout -b feature/your-feature-name

2. Make Changes¶

Follow our coding standards: - Use type hints - Write docstrings in Google format - Follow PEP 8 style guidelines - Add tests for new functionality

3. Run Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/test_planar_pcs_num.py

# Run with coverage
pytest --cov=soromox

To use the repository's Coverage.py configuration and produce the same report formats as the project tooling:

uv run --extra test make coverage
uv run --extra test make coverage_xml

4. Format and Lint Code¶

We use Ruff for both code formatting and linting. Ruff is configured in pyproject.toml and follows our project's style guidelines.

Command Line Usage¶

# Auto-format code
ruff format .

# Format specific directories
ruff format src tests examples

# Check formatting without making changes
ruff format --check .

# Run linting checks
ruff check .

# Auto-fix linting issues
ruff check --fix .

# Run both formatting and linting
ruff format . && ruff check .

You can also use the Makefile targets:

# Format code
make format

# Check formatting (for CI)
make format-check

VS Code Integration¶

For automated formatting on file save, install the Ruff VS Code extension. The project includes VS Code settings (see .vscode/settings.json) that configure:

• Ruff as the default formatter for Python files
• Format on save enabled
• Automatic import organization on save
• Automatic linting fixes on save

After installing the Ruff extension, your code will be automatically formatted and linted whenever you save a Python file.

Ruff Configuration¶

Ruff is configured in pyproject.toml with the following key settings: - Line length: 88 characters - Target Python version: 3.11+ - Enabled lint rules: pycodestyle, Pyflakes, isort, flake8-bugbear, and more - Quote style: double quotes - Import organization: first-party imports from soromox

For more details, see the [tool.ruff] section in pyproject.toml.

5. Build Documentation¶

The documentation site uses Zensical. Use its CLI for both local preview and production builds:

# Serve documentation locally
uv run --extra docs zensical serve

# Build documentation
uv run --extra docs zensical build --clean

6. Commit Changes¶

git add .
git commit -m "feat: add new robot system"

Use conventional commit messages: - feat: for new features - fix: for bug fixes - docs: for documentation changes - test: for test additions - refactor: for code refactoring

Extending SoRoMoX¶

For guidance on adding custom robot systems or renderers, see the Extending SoRoMoX guide which covers:

• Implementing custom soft robot systems
• Adding new renderer backends
• Contributing new controllers
• Understanding the base class interfaces
• Best practices for extensibility

Code Style¶

Python Style¶

• Follow PEP 8
• Use type hints for all function signatures
• Maximum line length: 88 characters
• Use descriptive variable names

Docstring Format¶

Use Google-style docstrings:

def forward_kinematics(params: PCSParams, q: Array) -> Array:
    """
    Compute forward kinematics for the robot.

    Args:
        params: Typed PCS parameters. Numeric fields are JAX arrays and can be
            replaced immutably with ``params.replace(...)``.
        q: Configuration vector of shape (n_dof,)

    Returns:
        End-effector position of shape (2,) for planar robots

    Raises:
        ValueError: If configuration vector has wrong dimensions

    Example:
        >>> params = params.replace(length=jnp.array([0.1]))
        >>> q = jnp.array([0.0, 0.0, -1.0])
        >>> pos = forward_kinematics(params, q)
    """

JAX Best Practices¶

• Use jax.numpy instead of numpy
• Make functions JAX-transformable (pure, no side effects)
• Use jit for performance-critical functions
• Avoid Python loops in favor of JAX operations

Testing Guidelines¶

Test Structure¶

import pytest
import jax.numpy as jnp
from soromox.systems import YourSystem

class TestYourSystem:
    def setup_method(self):
        """Set up test fixtures."""
        self.params = YourSystemParams(...)

    def test_forward_kinematics(self):
        """Test forward kinematics."""
        # Test implementation
        pass

    def test_jacobian_computation(self):
        """Test Jacobian computation."""
        # Test implementation
        pass

Test Coverage¶

Aim for high test coverage: - Unit tests for individual functions - Integration tests for complete workflows - Property-based tests for mathematical relationships - Regression tests for bug fixes

Documentation Guidelines¶

API Documentation¶

• Document all public functions and classes
• Include examples in docstrings
• Use type hints consistently
• Explain mathematical concepts clearly

User Documentation¶

• Write clear, step-by-step tutorials
• Include complete, runnable examples
• Explain the mathematical background
• Provide troubleshooting guides

Submitting Changes¶

1. Push Changes¶

git push origin feature/your-feature-name

2. Create Pull Request¶

• Provide a clear description of changes
• Reference related issues
• Include screenshots for UI changes
• Ensure all tests pass

3. Code Review¶

• Address reviewer feedback
• Update tests and documentation as needed
• Maintain a clean commit history

Getting Help¶

• Open an issue for bugs or feature requests
• Join discussions in pull requests
• Check existing documentation and examples
• Ask questions in the community

Maintainer releases¶

Version management and publication are maintainer-only workflows. The version and release guide documents the canonical branch and pull request process, tag automation, and recovery procedure.

Thank you for contributing to SoRoMoX!