Introduction

Welcome to the documentation of the FONSim library!

It is hoped that this documentation helps the reader in exploring FONSim. If something appears missing: no worries, please send an email to one of the developers and they’ll kindly try to help you forward.

How to get started with FONSim

It is suggested to follow the tutorials in this documentation. These ought to familiarize the reader with the basic usage of FONSim. Many users will want to extend FONSim, as the included standard functionality is unlikely to fully support their research case. They will want to continue into the code documentation, which discusses the five main parts of FONSim.

Installation: FONSim is available on the PyPI and therefore can be easily installed with pip install fonsim. For more detailed intallation instructions, see Installation.

Features

  • Powerful and fast simulation backend

    • Newton-Raphson method for handling nonlinear equations

    • Backward Euler time discretization for stability

  • Implicit component equations

  • Fluid class

    • custom fluids, e.g. non-Newtonian

    • fallback functionality

  • Toolset focused on soft robotics (SoRo) research

    • read and process pv-curves

  • Standard library of fluidic components

    • Tubes, nodes, pressure sources, volume sources, containers, one-way valves, …

  • Flow calculations

    • Compressible flow approximations

    • Laminar and turbulent flow based on Reynold number

    • Major and minor losses (Darcy, Haaland, K-factor etc.)

  • Preconfigured custom plot methods

  • Export data for further processing as JSON file

  • Cross platform

Goal and philosophy

The goal of FONSim is to greatly ease simulation of fluidic systems in softrobotics research by providing a set of often-needed system components and analysis tools and by automating the construction and solving of the resulting component and network equations with an open-source, easily extensible library.

FONSim is designed in the first place for usage in research environments, where flexibility and easy-to-experiment-with software are key. Therefore, FONSim is fully written in relatively easily-read Python code such that it is doable to inspect and extend FONSim without investing too much time and effort. While this choice for Python (versus, for example, C or C++) means that FONSim will not excel in solving speed, this is compensated for by Python being much easier to use. Finally, the speed difference is not that large, as for most of the time-consuming numerical maths the Numpy library is used, which under the hood relies on highly-optimized C and FORTRAN code.

FONSim does not have a GUI (Graphical User Interface). While this results in a steeper learning curve in the beginning, defining systems using code (and not using a GUI) does have two mayor advantages. The first advantage is that code is far more powerful that a GUI. Defining and connecting hundreds of system components can be done in a few lines using appropriate constructs such as for-loops. The second advantages is that Python code is eay to collaborate on and to version manage, for example using industry-standard tools like Git.

FONSim consists of five parts. While these parts depend on each other, they are not finely ingrained to increase flexibility and ease maintainability. The first part is the core and is application-agnostic (!). It is used just as easily to simulate kinematics as fluidic networks. Two other parts are the standard components and fluids, which define most common components used in softrobotics research. Finally, the three last parts provide some smaller functionality for data visualization, some data IO and a function generator.

Contributing

Ways to contribute to FONSim

There are several ways to contribute to the FONSim project:

  • Provide feedback about your usage experience.

  • Ask a question.

  • Suggest an improvement, be it to the documentation, the code or anything else.

  • Implement an improvement yourself - please see Contribution process.

For all the above, users can email one of the developers or open a new issue on GitLab issues. Once there are more developers, a more appropriate discussion place will be opened.

Contribution process

  1. Check for open issues or open a new issue.

  2. Fork the FONSim repository on GitLab.

  3. Make your changes. Don’t forget to add yourself to CONTRIBUTORS.txt!

  4. Send a pull request. If no response, email one of the maintainers.

Before submitting the pull request, as a general rule: - Any code change should come with appropriate tests and documentation. - All tests should pass.

FAQ

…