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 solves step-limited local surrogate subproblems 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
  • First-order and history-based quadratic FEA surrogates with L-BFGS subproblem solves and explicit step limits
  • Surface-integrated geometric penalties with fixed, sensitivity-based, or adaptive weights; native FEA sensitivities remain unscaled
  • Named load cases, ordered solve groups, and per-worker CPU/GPU assignment (one CPU worker by default)
  • UI definition, asset preview, saved-log browsing, per-surface/control-net views, and current-view geometry export and history GIF export
  • 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 logs, FEA files, design states, and a restart script into a timestamped result folder under the configured run root. The bending example matches ry=2 rad with a squared-error objective and a quadratic history surrogate.

  3. Graphical interface. The GUI supports problem definition, optimization monitoring, and result inspection in one window. It exports a runnable folder containing a same-named .py file and morphopt_assets/. Geometry inputs are restored from the definition beside the script; move the whole folder when transferring a task.

    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 folders. Load cases use named interface cards with individually labelled scalar parameters. Workspace objectives automatically register their boundary Gauss-point cases.

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/ — Boundary-surface shape optimization, geometric penalties, and weight strategies
    • 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.8

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.8
File Size Uploaded Provenance Actions
morphopt-4.0.8.tar.gz 509.7 kB Without provenance Details for morphopt-4.0.8.tar.gz

Built distribution (wheel)

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

Total release size: 1.1 MB

Release files / morphopt-4.0.8.tar.gz

Download URL morphopt-4.0.8.tar.gz
Size 509.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4f9ba39f41cdbd855acb440b1dd5c6a23e28fda2c30c076f921d29b3c1f0999e
BLAKE2b-256 checksum
How to use checksums
a59d97b950ddec363aa4953ed0340eccd71c899c1184099624d12334dd0a5f91
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.8-py3-none-any.whl

Download URL morphopt-4.0.8-py3-none-any.whl
Size 594.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a3b7600bbcfccf7b504453ebcd360a397c1e7fb8554fe90dc50bae3576fb983a
BLAKE2b-256 checksum
How to use checksums
54517967b0fe25a7dff447524983ad5d46c2bcc7f558cc10728972f7d078d539
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.8

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