|
|
|
### Welcome to the MBDyn Developers Wiki!
|
|
|
|
|
|
|
|
If you're just looking for information about what MBDyn is, what it can do and what you can do with it, please refer to the [MBDyn official website](http://www.mbdyn.org/).
|
|
|
|
In short, MBDyn is a general-purpose, [free](https://www.gnu.org/philosophy/free-sw.en.html) [Multibody Dynamics](https://en.wikipedia.org/wiki/Multibody_system) analysis software.
|
|
|
|
|
|
|
|
This Wiki will eventually become a place in which developers can get information that will speed up their learning curve about the code. At the moment, it contains some basic information primarily focused on the MBDyn [GSoC](https://summerofcode.withgoogle.com/) participation.
|
|
|
|
|
|
|
|
Please be aware that we, as MBDyn developers, believe strongly in the [free](https://www.gnu.org/philosophy/free-sw.en.html) software philosophy. In our daily work and in the MBDyn development and testing, we work with GNU/Linux as our primary OS. Therefore, to contribute to MBDyn you should be at least somewhat familiar with GNU/Linux.
|
|
|
|
|
|
|
|
### How to contribute
|
|
|
|
There are different ways you can contribute to MBDyn. For example:
|
|
|
|
- using it and reporting bugs (for example opening an [issue](https://public.gitlab.polimi.it/DAER/mbdyn/issues)), fixing/adding tutorials, documentation, suggesting new features, and so on;
|
|
|
|
- submitting code that fix bugs or implement new features, and so on;
|
|
|
|
- establishing a grant with [DAER/Polimi](http://www.aero.polimi.it/) to implement the features or develop the models you need (to establish a contact, please send an email to [mbdyn@aero.polimi.it](mailto:mbdyn@aero.polimi.it)).
|
|
|
|
|
|
|
|
If you feel to go with the second option (submitting code), please read carefully and follow our [Development Guidelines](Development-Guidelines)
|
|
|
|
### Google Summer of Code
|
|
|
|
We have been selected as participating Orgs in the [2015](https://www.mbdyn.org/?News&id=19), [2016](https://www.mbdyn.org/?News&id=28), [2017](https://www.mbdyn.org/?News&id=31), [2019](https://www.mbdyn.org/?News&id=36), [2020](https://www.mbdyn.org/?News&id=38), 2021, 2022 and **2024** [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com). You can find more information in the [dedicated Wiki page](https://public.gitlab.polimi.it/DAER/mbdyn/wikis/GSoC-and-MBDyn).
|
|
|
|
|
|
|
|
### Some Frequently Asked Questions
|
|
|
|
|
|
|
|
#### Where can I find the developers' manual?
|
|
|
|
The short answer is: __there is no developers' manual__, sorry. A more detailed answer is: it is being authored; a draft copy is distributed within code in [`manual/tecman`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/master/manual/tecman), but it's far from complete. Essentially, developers committed themselves to writing some technical documentation for each new feature that is added to the code, while features already implemented will get documented whenever they need review for whatever reason. Eventually, this document will become complete enough to be called "developers' manual".
|
|
|
|
|
|
|
|
#### How to Report a Bug?
|
|
|
|
The preferred method, since MBDyn moved to Gitlab, is to open an [Issue](https://public.gitlab.polimi.it/DAER/mbdyn/issues). Doing so will provide for better bug tracking and task assignments. Please make sure your request for help or bug report is well formulated. See Simon Tatham's ["How to Report Bugs Effectively"](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) or R. Clint Whaley's ["Why are you such a jerk when answering user questions? AKA: how can I help you feel good about providing me with support?"](http://math-atlas.sourceforge.net/faq.html#utone) for effective discussion of how help requests and bug reports should and SHOULD NOT be formulated. Many thanks to Simon and Clint for spelling out so clearly what we believe often are every free software developer's contrasting feelings with users. In general, before you post a request for help or report a bug, you should first:
|
|
|
|
- read the most appropriate documentation, including the [FAQs](https://www.mbdyn.org/Documentation/FAQ.html);
|
|
|
|
- search the MBDyn users mailing list [archives](https://lists.mbdyn.org/pipermail/mbdyn-users/): someone might have already addressed the same issue, and the answer could be already there;
|
|
|
|
- post your request, following the previously mentioned indications.
|
|
|
|
|
|
|
|
#### What are run-time loadable modules, and how do they work?
|
|
|
|
MBDyn supports run-time loadable modules. A run-time loadable module is a piece of code that is loaded during the execution of MBDyn through the `module load` statement, defined as
|
|
|
|
```
|
|
|
|
module load : <module_name> [ , <args> ... ] ;
|
|
|
|
```
|
|
|
|
where `<module_name>` is the name of the object that implements the module, which can be a full path (e.g. `libmodule-xxx.la`, `/usr/local/libexec/libmodule-yyy.la` or so).
|
|
|
|
Each module must provide a function declared as
|
|
|
|
```cpp
|
|
|
|
extern "C" int module_init(const char *module_name, void *pdm, void *php);
|
|
|
|
```
|
|
|
|
where the last two arguments give access to internal structures of the solver.
|
|
|
|
|
|
|
|
This function is invoked when the module is loaded. Any optional args that follow the module name can be interpreted within this function call.
|
|
|
|
|
|
|
|
The purpose of this function is usually to register some piece of code that may be used later. A typical use is to register the code that parses a user-defined drive caller, constitutive law, or even an element. Even fancier features can be augmented using run-time loadable modules.
|
|
|
|
|
|
|
|
Several examples of user-defined drive callers, constitutive laws, and elements are provided in subfolders of the [`modules/`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/master/modules) folder.
|
|
|
|
|
|
|
|
If you need something fancy, that cannot be directly obtained using the built-in library of entities, or you want to develop something that you don't want to share with other users (remember that the whole code is [GPL](https://public.gitlab.polimi.it/DAER/mbdyn/blob/master/LICENSE)), you should consider implementing it using a run-time loadable module.
|
|
|
|
|
|
|
|
Have a look at subfolders of the [`modules/`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/master/modules) folder, starting from those that are closer to what you want to implement; try to understand how things work, and make sure that you follow [these instructions](https://www.mbdyn.org/Documentation/FAQ.html#how-can-i-build-run-time-loadable-modules) when building MBDyn.
|
|
|
|
|
|
|
|
### Python Preprocessor
|
|
|
|
The documentation of the MBDyn Python Preprocessor can be found [here](PythonPreprocessor/MBDynLib) |
|
|
|
### Welcome to the MBDyn Developers Wiki!
|
|
|
|
|
|
|
|
If you're just looking for information about what MBDyn is, what it can do and what you can do with it, please refer to the [MBDyn official website](http://www.mbdyn.org/).
|
|
|
|
In short, MBDyn is a general-purpose, [free](https://www.gnu.org/philosophy/free-sw.en.html) [Multibody Dynamics](https://en.wikipedia.org/wiki/Multibody_system) analysis software.
|
|
|
|
|
|
|
|
This Wiki will eventually become a place in which developers can get information that will speed up their learning curve about the code. At the moment, it contains some basic information primarily focused on the MBDyn [GSoC](https://summerofcode.withgoogle.com/) participation.
|
|
|
|
|
|
|
|
Please be aware that we, as MBDyn developers, believe strongly in the [free](https://www.gnu.org/philosophy/free-sw.en.html) software philosophy. In our daily work and in the MBDyn development and testing, we work with GNU/Linux as our primary OS. Therefore, to contribute to MBDyn you should be at least somewhat familiar with GNU/Linux.
|
|
|
|
|
|
|
|
### How to contribute
|
|
|
|
There are different ways you can contribute to MBDyn. For example:
|
|
|
|
- using it and reporting bugs (for example opening an [issue](https://public.gitlab.polimi.it/DAER/mbdyn/issues)), fixing/adding tutorials, documentation, suggesting new features, and so on;
|
|
|
|
- submitting code that fix bugs or implement new features, and so on;
|
|
|
|
- establishing a grant with [DAER/Polimi](http://www.aero.polimi.it/) to implement the features or develop the models you need (to establish a contact, please send an email to [mbdyn@aero.polimi.it](mailto:mbdyn@aero.polimi.it)).
|
|
|
|
|
|
|
|
If you feel to go with the second option (submitting code), please read carefully and follow our [Development Guidelines](Development-Guidelines)
|
|
|
|
### Google Summer of Code
|
|
|
|
We have been selected as participating Orgs in the [2015](https://www.mbdyn.org/?News&id=19), [2016](https://www.mbdyn.org/?News&id=28), [2017](https://www.mbdyn.org/?News&id=31), [2019](https://www.mbdyn.org/?News&id=36), [2020](https://www.mbdyn.org/?News&id=38), 2021, 2022 and **2024** [Google Summer of Code (GSoC)](https://summerofcode.withgoogle.com). You can find more information in the [dedicated Wiki page](https://public.gitlab.polimi.it/DAER/mbdyn/wikis/GSoC-and-MBDyn).
|
|
|
|
|
|
|
|
### Some Frequently Asked Questions
|
|
|
|
|
|
|
|
#### Where can I find the developers' manual?
|
|
|
|
The short answer is: __there is no developers' manual__, sorry. A more detailed answer is: it is being authored; a draft copy is distributed within the code in [`manual/tecman`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/develop/manual/tecman) and the most recent version in PDF-format is distributed in [`tecman.pdf`](https://github.com/mmorandi/MBDyn-web/raw/main/userfiles/documents/tecman.pdf), but it's far from complete. Essentially, developers committed themselves to writing some technical documentation for each new feature that is added to the code, while features already implemented will get documented whenever they need review for whatever reason. Eventually, this document will become complete enough to be called "developers' manual".
|
|
|
|
|
|
|
|
#### How to Report a Bug?
|
|
|
|
The preferred method, since MBDyn moved to Gitlab, is to open an [Issue](https://public.gitlab.polimi.it/DAER/mbdyn/issues). Doing so will provide for better bug tracking and task assignments. Please make sure your request for help or bug report is well formulated. See Simon Tatham's ["How to Report Bugs Effectively"](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) or R. Clint Whaley's ["Why are you such a jerk when answering user questions? AKA: how can I help you feel good about providing me with support?"](http://math-atlas.sourceforge.net/faq.html#utone) for effective discussion of how help requests and bug reports should and SHOULD NOT be formulated. Many thanks to Simon and Clint for spelling out so clearly what we believe often are every free software developer's contrasting feelings with users. In general, before you post a request for help or report a bug, you should first:
|
|
|
|
- read the most appropriate documentation, including the [FAQs](https://www.mbdyn.org/Documentation/FAQ.html);
|
|
|
|
- search the MBDyn users mailing list [archives](https://lists.mbdyn.org/pipermail/mbdyn-users/): someone might have already addressed the same issue, and the answer could be already there;
|
|
|
|
- post your request, following the previously mentioned indications.
|
|
|
|
|
|
|
|
#### What are run-time loadable modules, and how do they work?
|
|
|
|
MBDyn supports run-time loadable modules. A run-time loadable module is a piece of code that is loaded during the execution of MBDyn through the `module load` statement, defined as
|
|
|
|
```
|
|
|
|
module load : <module_name> [ , <args> ... ] ;
|
|
|
|
```
|
|
|
|
where `<module_name>` is the name of the object that implements the module, which can be a full path (e.g. `libmodule-xxx.la`, `/usr/local/libexec/libmodule-yyy.la` or so).
|
|
|
|
Each module must provide a function declared as
|
|
|
|
```cpp
|
|
|
|
extern "C" int module_init(const char *module_name, void *pdm, void *php);
|
|
|
|
```
|
|
|
|
where the last two arguments give access to internal structures of the solver.
|
|
|
|
|
|
|
|
This function is invoked when the module is loaded. Any optional args that follow the module name can be interpreted within this function call.
|
|
|
|
|
|
|
|
The purpose of this function is usually to register some piece of code that may be used later. A typical use is to register the code that parses a user-defined drive caller, constitutive law, or even an element. Even fancier features can be augmented using run-time loadable modules.
|
|
|
|
|
|
|
|
Several examples of user-defined drive callers, constitutive laws, and elements are provided in subfolders of the [`modules/`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/master/modules) folder.
|
|
|
|
|
|
|
|
If you need something fancy, that cannot be directly obtained using the built-in library of entities, or you want to develop something that you don't want to share with other users (remember that the whole code is [GPL](https://public.gitlab.polimi.it/DAER/mbdyn/blob/master/LICENSE)), you should consider implementing it using a run-time loadable module.
|
|
|
|
|
|
|
|
Have a look at subfolders of the [`modules/`](https://public.gitlab.polimi.it/DAER/mbdyn/tree/master/modules) folder, starting from those that are closer to what you want to implement; try to understand how things work, and make sure that you follow [these instructions](https://www.mbdyn.org/Documentation/FAQ.html#how-can-i-build-run-time-loadable-modules) when building MBDyn.
|
|
|
|
|
|
|
|
### Python Preprocessor
|
|
|
|
The documentation of the MBDyn Python Preprocessor can be found [here](PythonPreprocessor/MBDynLib) |
