mystica

Multi bodY SimulaTor maxImal CoordinAtes

mystica is a MATLAB library to simulate the kinematics and dynamics of multibody systems. mystica computes the system evolution by modeling the problem using a state definition that we define maximal. The maximal representation consists of a set of non-minimum variables 𝐪 complemented by the holonomic constraint g(𝐪) = 0.

---

⚠️ REPOSITORY UNDER DEVELOPMENT ⚠️
The libraries implemented in this repository are still experimental, and we cannot guarantee a stable API.

---

Table of Contents

• 🔨 Dependencies
• 💾 Installation
• 🚀 Usage
• ⚙️ Contributing
• Citing this work
• Maintainer

🔨 Dependencies

• MATLAB
• MATLAB Curve Fitting Toolbox for the smooth function
• A MATLAB supported compiler for MEX-file compilation

Other requisites are:

• CasADi
• yamlmatlab

Both CasADi and yamlmatlab are downloaded and configured in the Installation section.

💾 Installation

1. Clone the repo:

git clone https://github.com/ami-iit/mystica.git
cd mystica

2. Run the install() function in MATLAB.

install()

The install() function downloads mambaforge. mambaforge is a package manager that downloads and configures our dependencies in a conda environment called mystica.

If you already have mambaforge

If you already have mambaforge configured, you can call the install() function by defining the mambaforge_prefix value:

install('mambaforge_prefix',<your mambaforge path prefix>)

⚠️ Known issue For some versions of Ubuntu and MATLAB, MATLAB is not able to load the required libraries like CasADi (see issue). A possible workaround is to launch matlab with LD_PRELOAD:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 matlab

🚀 Usage

Before every usage, remember to run the autogenerated MATLAB file called deps/setup.m to set up the MATLABPATH.

Alternatively, you can launch MATLAB from the terminal after activating the conda environment called mystica:

conda activate mystica
matlab

Here's a snippet of code to simulate the kinematics of a 4-bar linkage mechanism:

model = mystica.model.getModel4BarLinkage();
stgs = mystica.stgs.getDefaultSettingsSimKinRel(model);
data = mystica.runSimKinRel('model', model, 'stgs', stgs, 'mBodyPosQuat_0', model.getMBodyPosQuatRestConfiguration, 'nameControllerClass', 'mystica.controller.ExampleKinRel');
mystica.viz.visualizeKinRel('model', model, 'data', data, 'stgs', stgs)

Other examples can be found in the examples directory.

If you want to delve deeper into the code, we have prepared this document as an entry point to explain and describe our variables.

⚙️ Contributing

mystica is an open-source project, and is thus built with your contributions. We strongly encourage you to open an issue with your feature request. Once the issue has been opened, you can also proceed with a pull-request. 🚀

Citing this work

If you find the work useful, please consider citing:

@ARTICLE{9793615,
  author={Bergonti, Fabio and Nava, Gabriele and Fiorio, Luca and L’Erario, Giuseppe and Pucci, Daniele},
  journal={IEEE Transactions on Robotics},
  title={Modeling and Control of Morphing Covers for the Adaptive Morphology of Humanoid Robots},
  year={2022},
  volume={38},
  number={5},
  pages={3300-3313},
  doi={10.1109/TRO.2022.3170281}}

Maintainer

This repository is maintained by:

	@FabioBergonti