Skip to main content

MorphOpt — A Differentiable Optimization Framework for Soft Structure & Morphology Design

Developed by Zenan Song

MorphOpt is a differentiable structural optimization framework that combines the adjoint method with automatic differentiation (AD). The sensitivity corresponds to the virtual work of residual force derivatives on the adjoint displacement field, computed via a single backpropagation through the residual graph. MorphOpt provides a unified interface for geometry, load, and material definition, calls torchfea for GPU-accelerated differentiable nonlinear FEA and adjoint-AD sensitivity, and employs a trust-region optimizer with L-BFGS for design updates. Validated on SIMP topology optimization with B-spline density fields and pneumatic soft robot shape optimization with deformation-dependent follower loads.

Features

  • Custom model definition covering geometry, material, and load parameters
  • Differentiable FEA via torchfea with automatic solving and sensitivity propagation
  • L-BFGS and trust-region methods for parameter updates within a subproblem framework
  • Component customization through framework class inheritance

Quick Start

Install the package:

pip install morphopt

Requirements: Python ≥ 3.12; a PyTorch float64 build is recommended.

Optimizations are run as scripts. Each job is an ordinary Python file that calls morphopt.start_optimization(...). It runs headlessly in a terminal (local or remote), and optimization runs can be stopped and resumed from their result folders. Script execution is the recommended way to run jobs.

  1. Run a minimal example — execute it directly in a terminal:

    # Shape optimization (pneumatic bending actuator)
    python examples/bending_actuator/bending_actuator.py
    
    # SIMP topology optimization (compliant gripper)
    python examples/simp_gripper/simp_gripper.py
    
  2. Run a custom job — copy an example as a starting point, configure the geometry, material, loads, updater, and objective, and launch it as a script:

    python my_task.py
    

    Each run writes its results (logs, FEA files, restart script) into a timestamped result folder under the run root.

  3. Graphical interface. The GUI supports problem definition, optimization monitoring, and result inspection in one window. It also exports runnable Python scripts (.py) for execution in the UI or a terminal.

    morphopt-ui            # console command, available after `pip install morphopt`
    # Alternative entry point: python -m morphopt.ui
    

The GUI opens directly into the full definition workbench with its standard sections present and no problem setup prefilled. Definitions can be created directly in the workbench or generated through Quickstart. Quickstart provides shape and topology optimization settings, geometry definitions, and weighted objective terms with associated load conditions. Workspace terms select their driving pressure channels and use boundary integration. Generated problems stay editable and can be saved or exported as runnable scripts.

The UI quick start covers the complete example from model definition to optimization and result inspection. The script quick start provides the equivalent runnable Python task.

Run the UI in a virtual environment

Create and activate a Conda environment, then install and launch MorphOpt:

conda create -n morphopt python=3.12
conda activate morphopt
python -m pip install morphopt
morphopt-ui

For an existing environment, activate it instead. To run the source checkout, install the project in editable mode from its root directory:

conda activate morphopt
cd /path/to/morphopt
python -m pip install -e .
morphopt-ui

Replace the environment name and project path as appropriate. Installation is required once per environment; subsequent launches require only environment activation and the launch command. The equivalent module entry point uses the active environment's Python interpreter:

python -m morphopt.ui

Numeric configuration

Shared UI defaults and tunable kernel parameters live in src/morphopt/constants.py, grouped under CONSTANT.UI and CONSTANT.KERNEL. Code accesses them directly, for example CONSTANT.UI.VIEWER.RENDER.LABEL_FONT_SIZE or CONSTANT.KERNEL.SOLVER.NUM_PROCESS. Edit a value there to change its default; restart MorphOpt for the change to take effect. Coordinate indices, tensor dimensions, and coefficients that define mathematical formulas remain in code. UI translations remain in JSON files under src/morphopt/ui/locales/.

Documentation

Workflow Quick start Module and interface reference
Python script Start an optimization Define and extend each module
Graphical UI Create and run the example Modules, parameters and interface definitions

The documentation index includes the reading order and automatic section numbering commands. Theory and code architecture are documented separately under docs/theory/ and docs/codestructure/.

Directory Overview

  • src/morphopt/
    • optcore — Core package (controller, params, solver, objective, updaters)
    • shapeopt/ — B-spline shape optimization
    • simp/ — SIMP topology optimization
    • codesign/ — Shell co-design (shape + material)
    • ui/ — PySide6 graphical UI (definition + observer in one window)
  • examples/ — Runnable tasks, UI definitions, input geometry assets, and case notes
  • docs/ — Usage guides, API reference, theory papers
  • tests/ — Gradient checks, geometry tests, UI tests
  • ui_runs/ — runs launched from the UI and their results (<label>_T<timestamp>/)

License

Research use preferred. For production or commercial use, please evaluate and ensure numerical and engineering robustness first.

Citation

Research using MorphOpt can cite the following publications:

  • TRO 2023
@ARTICLE{10296178,
  author={Chen, Feifei and Song, Zenan and Chen, Shitong and Gu, Guoying and Zhu, Xiangyang},
  journal={IEEE Transactions on Robotics}, 
  title={Morphological Design for Pneumatic Soft Actuators and Robots With Desired Deformation Behavior}, 
  year={2023},
  volume={39},
  number={6},
  pages={4408-4428},
  keywords={Shape;Surface morphology;Robots;Splines (mathematics);Pneumatic systems;Actuators;Soft robotics;Morphological design;shape optimization;pneumatic soft robots},
  doi={10.1109/TRO.2023.3323825}}
  • TRO 2026
@ARTICLE{11617347,
  author={Song, Zenan and Chen, Feifei and Gu, Guoying and Zhu, Xiangyang},
  journal={IEEE Transactions on Robotics}, 
  title={Continuum Jacobian-Based Computational Morphogenesis for Soft Robotic Workspace Optimization}, 
  year={2026},
  volume={42},
  number={},
  pages={3048-3068},
  keywords={Optimization;Design methodology;Surfaces;Modeling;End effectors;Shape;Soft robotics;Deformation;Vectors;Robots;Computational morphogenesis;Jacobian shape derivative;soft robotics;workspace optimization},
  doi={10.1109/TRO.2026.3716051}}

  • TMECH 2026
@ARTICLE{11536090,
  author={Song, Zenan and Zhou, Guozhen and Chen, Feifei},
  journal={IEEE/ASME Transactions on Mechatronics}, 
  title={Contact-Aware Soft Robot Design via Differentiable Simulation and Morphological Optimization}, 
  year={2026},
  volume={31},
  number={4},
  pages={4576-4584},
  keywords={Contacts;Optimization;Modeling;Design methodology;Soft robotics;Surfaces;Actuators;Materials;Force;Simulation;Differentiable contact modeling;morphological design;soft robotics},
  doi={10.1109/TMECH.2026.3692920}}

Metadata

Release files for morphopt 4.0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for morphopt 4.0.7
File Size Uploaded Provenance Actions
morphopt-4.0.7.tar.gz 491.6 kB Without provenance Details for morphopt-4.0.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for morphopt 4.0.7
File Interpreter ABI Platform Actions
morphopt-4.0.7-py3-none-any.whl Python 3 none any Details for morphopt-4.0.7-py3-none-any.whl

Total release size: 1.1 MB

Release files / morphopt-4.0.7.tar.gz

Download URL morphopt-4.0.7.tar.gz
Size 491.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d68c691e25ef8ec550e02888f5ecf582976a22b69d488e7201d605b88a7caec4
BLAKE2b-256 checksum
How to use checksums
0ed2eac28af6c176cf08c039940c606177541923fa1443688991dc527ee9b588
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"CachyOS Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / morphopt-4.0.7-py3-none-any.whl

Download URL morphopt-4.0.7-py3-none-any.whl
Size 573.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cd4b897f0e1baf62eee40df7c8b9031a4def7f97a5faad1ab97246b12f885dfc
BLAKE2b-256 checksum
How to use checksums
2fb2b89798b52c8a75b54c5628dac9577d0a18a33c08ab88a938993b2242afc7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"CachyOS Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for morphopt 4.0.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page