{"id":20671488,"url":"https://github.com/bertoldi-collab/difflexmm","last_synced_at":"2025-04-19T18:38:44.537Z","repository":{"id":260343177,"uuid":"763359866","full_name":"bertoldi-collab/DifFlexMM","owner":"bertoldi-collab","description":"Differentiable Flexible Mechanical Metamaterials","archived":false,"fork":false,"pushed_at":"2024-12-05T03:05:22.000Z","size":40032,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T11:41:44.438Z","etag":null,"topics":["architected-materials","automatic-differentiation","differentiable-physics","differentiable-simulations","inverse-design","mechanical-metamaterials","metamaterial-design","nonlinear-dynamics","nonlinear-optimization","nonlinear-waves"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bertoldi-collab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-26T06:29:00.000Z","updated_at":"2025-03-13T22:08:21.000Z","dependencies_parsed_at":"2024-12-05T04:28:09.638Z","dependency_job_id":null,"html_url":"https://github.com/bertoldi-collab/DifFlexMM","commit_stats":null,"previous_names":["bertoldi-collab/difflexmm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoldi-collab%2FDifFlexMM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoldi-collab%2FDifFlexMM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoldi-collab%2FDifFlexMM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoldi-collab%2FDifFlexMM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bertoldi-collab","download_url":"https://codeload.github.com/bertoldi-collab/DifFlexMM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249766393,"owners_count":21322587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architected-materials","automatic-differentiation","differentiable-physics","differentiable-simulations","inverse-design","mechanical-metamaterials","metamaterial-design","nonlinear-dynamics","nonlinear-optimization","nonlinear-waves"],"created_at":"2024-11-16T20:27:37.778Z","updated_at":"2025-04-19T18:38:44.530Z","avatar_url":"https://github.com/bertoldi-collab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DifFlexMM\n\n![Made with Python](https://img.shields.io/badge/Made%20with-Python-blue?logo=python\u0026logoColor=ecf0f1\u0026labelColor=34495e)\n[![Python tests](https://github.com/bertoldi-collab/DifFlexMM/actions/workflows/python_tests.yml/badge.svg)](https://github.com/bertoldi-collab/DifFlexMM/actions/workflows/python_tests.yml)\n[![Paper](https://img.shields.io/badge/Paper-10.1038/s41563--024--02008--6-blue?logoColor=ecf0f1\u0026labelColor=34495e)](https://doi.org/10.1038/s41563-024-02008-6)\n[![DOI](https://img.shields.io/badge/Data-10.5281/zenodo.12823471-blue?logo=zenodo\u0026logoColor=ecf0f1\u0026labelColor=34495e)](https://doi.org/10.5281/zenodo.12823471)\n[![arXiv](https://img.shields.io/badge/arXiv-2403.08078-b31b1b?logo=arXiv\u0026logoColor=arXiv\u0026labelColor=34495e)](https://arxiv.org/abs/2403.08078)\n[![GitHub license](https://img.shields.io/github/license/bertoldi-collab/DifFlexMM?labelColor=34495e)](https://github.com/bertoldi-collab/DifFlexMM/blob/main/LICENSE)\n[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Fbertoldi-collab%2FDifFlexMM\u0026count_bg=%2327AE60\u0026title_bg=%2334495E\u0026icon=github.svg\u0026icon_color=%23E7E7E7\u0026title=Hits\u0026edge_flat=false)](https://hits.seeyoufarm.com)\n\n**Dif**ferentiable **Flex**ible **M**echanical **M**etamaterials\n\nhttps://github.com/user-attachments/assets/8e966e96-13d4-439b-a0cb-d7dff115e7e1\n\n## 🌅 Why DifFlexMM?\n\n🚀 The goal of this framework is to push the boundary of designable dynamic behaviors achievable by nonlinear mechanical metamaterials.\n\n🤖 Through the power of differentiable simulations, the framework removes the typical limitations of metamaterial design e.g. periodicity, intuition-based design, manual tuning, single-task design, etc., and enables the automated discovery of non-periodic, multi-functional, and reprogrammable metamaterials in the nonlinear dynamic regime.\n\n## 🚁 Overview\n\nThis repository provides a fully differentiable dynamic design framework for 2D flexible mechanical metamaterials i.e. a network of rigid units connected by flexible ligaments.\nThe main physical ingredients of the model are:\n\n- 🥌 Rigid-body kinematics of the units.\n- 🎈 Elastic ligaments modeled by customizable energy functions.\n- 💥 Energy-based contact interactions between rigid units.\n\nWith these ingredients, flexible mechanical metamaterials define a rich space of nonlinear dynamic behaviors that can be navigated by the framework.\n\n🔭 From a high-level perspective, the framework facilitates the construction of the mapping between design parameters and the desired behavior of the metamaterial system.\n\n![Code mapping](docs/code_mapping.svg)\n\nBy leverging [JAX](https://github.com/google/jax), this complex mapping is implemented in a differentiable fashion, thus allowing gradients to flow through the entire dynamic simulation.\nIn particular, differentiability is provided with respect to:\n\n- Geometric paramaters: arbitrary parametrizations can be defined in the [`geometry`](difflexmm/geometry.py) module.\n- Ligament paramaters: energy functions can be defined in the [`energy`](difflexmm/energy.py) module.\n- Damping parameters: linear viscous damping as defined in the [`loading`](difflexmm/loading.py) module.\n- Driving parameters: arbitrary driving functions can be applied to any degree of freedom.\n- Loading parameters: arbitrary loading functions can be applied to any degree of freedom.\n- Initial conditions: initial positions and velocities of the system.\n- and any other paramater present in the [`ControlParams`](difflexmm/utils.py#L145-L163) data structure.\n\nThe main entry point of the simulator is the [`setup_dynamic_solver(...)`](difflexmm/dynamics.py#L60) in the [`dynamics`](difflexmm/dynamics.py) module.\nThis function takes all the fixed mappings (geometry, energy, loading, etc.) and returns a differentiable function that simulates the metamaterial dynamics.\nArbitrary forward problems can be defined by chaining this simulator function with any desired objective function.\n\n## 📜 Paper\n\nThis repository contains all the code developed for the paper:\n\n\u003e [G. Bordiga, E. Medina, S. Jafarzadeh, C. Boesch, R. P. Adams, V. Tournat, K. Bertoldi. Automated discovery of reprogrammable nonlinear dynamic metamaterials. _Nature Materials_. (2024).](https://doi.org/10.1038/s41563-024-02008-6)\n\n## 🎯 Solved design problems\n\nThe framework has been used to design a variety of mechanical metamaterials with different functionalities.\n\n|  | Task/tasks description | Notebooks | Data 💾 | Video |\n| --- | --- | --- | --- | --- |\n| 🌟 | Focusing energy at a single target location | [Quads](notebooks/quads_focusing_3dp_pla_shims.ipynb), [Kagome](notebooks/kagome_focusing_3dp_pla_shims.ipynb) | [Quads](data/quads_focusing_3dp_pla_shims), [Kagome](data/kagome_focusing_3dp_pla_shims) | [Quads](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/ff76f0bc-463d-49c4-83bb-278f301af246), [Kagome](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/537a6e32-c62d-4fdc-8a9d-e4762fda8a21) |\n| ️🗡️ | Splitting energy between different target locations | [Quads](notebooks/quads_energy_splitting_3dp_pla_shims.ipynb) | [Quads](data/quads_energy_splitting_3dp_pla_shims) | [Quads](https://github.com/user-attachments/assets/7b8ea46b-ccde-4f3f-8c04-e4f9015d62e5) |\n| ✨ | Focusing multiple inputs at the same target location | [Quads](notebooks/quads_focusing_multi_input_3dp_pla_shims.ipynb) | [Quads](data/quads_focusing_multi_input_3dp_pla_shims) | [Quads](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/fda885c3-ffd6-4b67-a19e-ad59d5f52a96) |\n| ️💫 | Reprogramming focusing target via static pre-compression | [Quads](notebooks/quads_focusing_switching_static_tuning_3dp_pla_shims.ipynb) | [Quads](data/quads_focusing_switching_static_tuning_3dp_pla_shims) | [Quads](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/5fa5cd61-f7dc-44b4-824c-6929818e7755) |\n| 🌟🛡️ | Switching between focusing and protection task | [Quads](notebooks/quads_focusing_vs_protection_static_tuning_3dp_pla_shims.ipynb) | [Quads](data/quads_focusing_vs_protection_static_tuning_3dp_pla_shims) | [Quads](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/ad4f9811-e623-4867-af42-c36ee31bcfbb) |\n| 🌀 | Nonlinear motion conversion | [Quads](notebooks/quads_spin_3dp_pla_shims.ipynb) | [Quads](data/quads_spin_3dp_pla_shims) | [Quads](https://github.com/bertoldi-collab/DifFlexMM/assets/16863374/9aa2bbc9-cbe0-4896-8c83-ce67f2c61af3) |\n\n💾 All data generated or used for the paper can be downloaded from [![DOI](https://img.shields.io/badge/Data-10.5281/zenodo.12823471-blue?logo=zenodo\u0026logoColor=ecf0f1\u0026labelColor=34495e)](https://doi.org/10.5281/zenodo.12823471).\nTo access and visualize the data:\n\n- Extract `data.zip` in the root directory of the repository.\n- Load and visualize optimization results for all the solved problems using the provided [notebooks](notebooks).\n- Load and visualize experimental data using the notebooks in the [exp](exp) folder.\n\n## ⬇️ Installation\n\n### DifFlexMM only\n\nAssuming you have access to the repo and ssh keys are set up in your GitHub account, you can install the package with\n\n```bash\npip install git+ssh://git@github.com/bertoldi-collab/DifFlexMM.git\n```\n\n### DifFlexMM with examples of solved design problems\n\nClone the repository, `cd` into the `DifFlexMM` folder, and install with\n\n```bash\npip install -e .\n```\n\n## 🤝 Contributing\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExpand here\u003c/b\u003e\u003c/summary\u003e\n\nThe dependency management of the project is done via [poetry](https://python-poetry.org/docs/).\n\nTo get started:\n\n- Install [poetry](https://python-poetry.org/docs/).\n- Clone the repository.\n- `cd` into the root directory and run `poetry install`. This will create the poetry environment with all the necessary dependencies.\n- If you are using vscode, search for `venv path` in the settings and paste `~/.cache/pypoetry/virtualenvs` in the `venv path` field. Then select the poetry enviroment as python enviroment for the project.\n\n\u003c/details\u003e\n\n## 📝 Citation\n\nIf you use this code in your research or anywhere, please cite the paper:\n\n```bibtex\n@article{bordiga_2024,\n    title   = {Automated Discovery of Reprogrammable Nonlinear Dynamic Metamaterials},\n    author  = {Bordiga, Giovanni and Medina, Eder and Jafarzadeh, Sina and B{\\\"o}sch, Cyrill and Adams, Ryan P. and Tournat, Vincent and Bertoldi, Katia},\n    year    = {2024},\n    journal = {Nature Materials},\n    volume  = {23},\n    number  = {11},\n    pages   = {1486--1494},\n    issn    = {1476-4660},\n    doi     = {10.1038/s41563-024-02008-6},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertoldi-collab%2Fdifflexmm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbertoldi-collab%2Fdifflexmm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertoldi-collab%2Fdifflexmm/lists"}