README.md 4.9 KB
Newer Older
Arne Baeyens's avatar
Arne Baeyens committed
1
2
# FONSIM
#### _Fluidic Object-oriented Network SIMulator_
abaeyens's avatar
readme    
abaeyens committed
3
4
5
6
7

An object-oriented Python 3 library designed for simulating pneumatic and hydraulic systems in soft robots.

This project is available under the GNU Affero General Public License v3.0 (**agpl-3.0**) license.

Arne Baeyens's avatar
Arne Baeyens committed
8
9
10
11
12
13
14
15
16
17
### Installation
The pre-packaged release version can be installed using `pip install fonsim`.
See the [PyPi page](https://pypi.org/project/fonsim/) for more information.

Currently, FONSIM resides in an early alpha stage.
Not all features work yet and you will encounter bugs.
We look forward to your feedback.
Thank you for your understanding.


abaeyens's avatar
readme    
abaeyens committed
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
### 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



### How to get started
Arne Baeyens's avatar
Arne Baeyens committed
41
The [examples directory](https://gitlab.com/abaeyens/fonsim/-/tree/master/examples) contains a set of examples showcasing various features of the simulator.
abaeyens's avatar
readme    
abaeyens committed
42
43
44
We suggest to start with running the examples.
Furthermore you may want to consult the documentation on
[readthedocs.org]().
Arne Baeyens's avatar
Arne Baeyens committed
45
__Note__: documentation is a WIP, not yet available.
abaeyens's avatar
readme    
abaeyens committed
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
The same documentation is also available by the
[Python help function](https://www.programiz.com/python-programming/docstrings#help).
If something is not fully clear, please let us know.

### Dependencies
* matplotlib
* numpy
* scipy



## Project development, contribution

### Contributing
Are you interested in contributing to this project?
Please get in touch so we can coordinate the development!
62

abaeyens's avatar
readme    
abaeyens committed
63
64
65
66
67
68
69
70
71
72
73
74
### Branching
The FONS project branching is based on the
[Driessen or git-flow model](https://nvie.com/posts/a-successful-git-branching-model/).
Put simply,
the `master` branch is reserved for production-ready code.
All software in `master` should be stable and usable.
The `dev` branch contains the latest developed features,
yet as a result the software is not as stable.
The actual features (and improvements in general) are developed in the
feature branches, for example `feature-plotting`.

### To get this repo locally
75
76
77
1. Clone the repo (notice the `$` - this means to do it in a terminal/console).
The directory with the project will be located in the current working directory of the terminal.
    ```
Arne Baeyens's avatar
Arne Baeyens committed
78
    $ git clone git@gitlab.com:abaeyens/fonsim.git
79
80
81
    ```
1. Go in the created directory (note: one can use `TAB` for autocompletion)
    ```
Arne Baeyens's avatar
Arne Baeyens committed
82
    $ cd fonsim
83
    ```
abaeyens's avatar
abaeyens committed
84

abaeyens's avatar
readme    
abaeyens committed
85
86
87
### Create a local install
A local install allows to try out the library locally.
This can be useful during development.
abaeyens's avatar
abaeyens committed
88
89
First, rename the project root directory to `fonsim` (default name after Git clone: `fons`).
Second, run in the project root directory:
abaeyens's avatar
readme    
abaeyens committed
90
```
abaeyens's avatar
abaeyens committed
91
$ python -m pip install -e .
abaeyens's avatar
readme    
abaeyens committed
92
```
abaeyens's avatar
abaeyens committed
93
94
95
96
97
98
99
This installs the FONS package such that it is accessible
like all other Python packages, e.g. using `import fonsim`.
The `-e` option denotes that it uses a symbolic link:
code changes in the project directory (including branch switching)
take effect at the first following `import`.
No re-installation is required.

abaeyens's avatar
readme    
abaeyens committed
100
101
102
103
104
Note: `python` should refer to Python 3.
You may have to write `python3` to avoid using Python 2. 

Note: there appear to be problems with this method on some Windows machines.

abaeyens's avatar
abaeyens committed
105
106
107
108
109
110
Note: if you want to install several versions of the same package on your system,
for example a stable version from PyPi
and a development version from a local install,
you may want to use a
[Python virtual environment](https://docs.python.org/3/tutorial/venv.html).

abaeyens's avatar
readme    
abaeyens committed
111
112
113
114
115
116
117
### Development tools
A git repository history visualizer tool like
[gitg](https://wiki.gnome.org/Apps/Gitg/)
can be helpful in developing this software.
It shows the relations between version branches visually,
lists all commits and allows to see the exact changes
were made in a particular commit.
Arne Baeyens's avatar
Arne Baeyens committed
118
In addition, it can show uncommitted changes.
abaeyens's avatar
readme    
abaeyens committed
119
120

Gitlab provides similar tools as a web version like the
Arne Baeyens's avatar
Arne Baeyens committed
121
[GitLab graph](https://gitlab.com/abaeyens/fonsim/-/network/master).
abaeyens's avatar
readme    
abaeyens committed
122

abaeyens's avatar
abaeyens committed
123
124
### Style guide
https://google.github.io/styleguide/pyguide.html.
abaeyens's avatar
readme    
abaeyens committed
125

Arne Baeyens's avatar
Arne Baeyens committed
126
127
128
129
### Contributors
Arne Baeyens  
Bert Van Raemdonck  

abaeyens's avatar
readme    
abaeyens committed
130
131
132
133
134

## Problems, questions, suggestions
If you have a question the FAQ section does not answer sufficiently,
or you think you have encountered a bug,
you can reach out by creating an issue on the
Arne Baeyens's avatar
Arne Baeyens committed
135
136
[GitLab Issues](https://gitlab.com/abaeyens/fonsim/-/issues) page.
The issues page is also the proper place to post suggestions and feedback.
abaeyens's avatar
readme    
abaeyens committed
137
138
139
140


## FAQ
...