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/bendingactuator.py
    
    # SIMP topology optimization (compliant gripper)
    python examples/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.

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/ — Example tasks (bending actuator, gripper, etc.)
  • 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.2

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.2
File Size Uploaded Provenance Actions
morphopt-4.0.2.tar.gz 420.6 kB Without provenance Details for morphopt-4.0.2.tar.gz

Built distribution (wheel)

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

Total release size: 913.0 kB

Release files / morphopt-4.0.2.tar.gz

Download URL morphopt-4.0.2.tar.gz
Size 420.6 kB
Tags Source
SHA-256 checksum
How to use checksums
5f251ac0155d71ae9957d963b5c61fc51c9ca7199816ed4fd47ef1289fb38518
BLAKE2b-256 checksum
How to use checksums
d791a0b3796f303485c154ed670d999000640a91a2260835b18f848258436820
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.2-py3-none-any.whl

Download URL morphopt-4.0.2-py3-none-any.whl
Size 492.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e4fa6d6787acf64133b05d91e4b21af0d410bb53b43b9764d687707c074b44b8
BLAKE2b-256 checksum
How to use checksums
b6b261873a33c4b1c63ac659dbf5a968bb044b475ea1b3d93217206b4d646762
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.2

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