6 SimGrid is a free software, written by a community of people. It
7 started as a little software to help ourselves in our own research,
8 and as more people put their input into the pot, it turned into
9 something that we hope to be valuable to many people. So yes. We hope
10 that SimGrid is helping you doing what you want, and that you will
11 join our community of happy simgriders.
13 Contacting the community
14 ------------------------
16 There are several locations where you can connect and discuss about
17 SimGrid. If you have a question, please have a look at the
18 documentation and examples first, but if some remain don't hesitate to
19 ask the community for help. If you do not have a question, just come
20 to us and say hello! We love earing about how people use SimGrid.
22 - For questions or remarks, drop us an email on the `user mailing
23 list <mailto:simgrid-user@lists.gforge.inria.fr>`_ (to subscribe,
24 visit the `web interface
25 <http://lists.gforge.inria.fr/mailman/listinfo/simgrid-user>`__);
26 you can also check out `our archives
27 <http://lists.gforge.inria.fr/pipermail/simgrid-user/>`_. We
28 prefer you to **not use private emails**. SimGrid is an open
29 framework, and you never know who have the time and knowledge to
30 answer your question, so please keep messages on the public mailing
33 - If you want to chat with the community, join us on `Mattermost
34 <https://framateam.org/simgrid/channels/town-square>`_. Be warned
35 that even if many people are connected to the channel, they may not
36 be staring at their chat windows. So don't be surprised if you
37 don't get an answer in the second, and please be patient.
39 If you prefer, you can reach us on IRC on \#simgrid at
40 ``irc.debian.org`` (the `logs are available
41 <http://colabti.org/irclogger/irclogger_logs/simgrid>`_). When no
42 non-french speaker are connected, we usually chat in french on
43 these channel, but we do switch back to english when we have a
46 - Asking your question on
47 `StackOverflow <http://stackoverflow.com/questions/tagged/simgrid>`_
48 is also a good idea, as this
49 site is very well indexed. We answer questions there too (don't
50 forget to use the SimGrid tag in your question so that we can see
51 it), and they remain usable for the next users.
53 Giving back to SimGrid
54 ----------------------
56 We are sometimes asked by users how to give back to the project. Here
57 are some ideas, but if you have new ones, feel free to share them with us.
59 Provide fresh-eyes feedback
60 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
62 We are working on the project since years. We take for granted things that are hard to infer at first, and traps we don't even see anymore.
63 Likewise, it's hard for us to maintain the documentation uptodate with the current situation, because we don't rely on the doc when navigating the project.
64 This is why your first impression as a newcomer to the project is utterly precious for us.
65 Please make sure to write a `discovery report <https://diff.wikimedia.org/2014/03/25/seeing-through-the-eyes-of-new-technical-contributors/>`_ to enlight us.
66 You can send it either as a bug report, as a mail on the list or simply post it as is to the Mattermost channel.
71 A simple way to help the SimGrid project is to **use SimGrid for your research, and say so**.
72 `Cite the SimGrid framework<https://simgrid.org/publications.html>`_ in your papers and speak of it with your colleagues to spread the word.
73 The number of publications enabled by SimGrid is really important when asking for further fundings to sustain the project:
74 The more you use the framework, the better for us.
76 Add a link to the `SimGrid homepage <https://simgrid.org>`_ on your site to improve our ranking in search engines.
78 You can also **help us constituting an active and welcoming user community**. Answer to the question sent to the mailing lists if you can, gently pointing to
79 the relevant part of the documentation on need, and help newscomers becoming part of our community too.
81 Finally, you can invite us for a talk on SimGrid to events you organize.
82 We have various format, ranging from a focused `20 minute talks <http://people.irisa.fr/Martin.Quinson/blog/2020/1124/SimGrid_presentations>`_
83 to a `45mn dense tutorial <http://people.irisa.fr/Martin.Quinson/blog/2012/1120/Simgrid_at_Louvain/>`_,
84 to a `2 hours seminar <http://people.irisa.fr/Martin.Quinson/blog/2016/0524/Experimental_methodology_for_distributed_systems>`_, or
85 even to `multi-days events <https://simgrid.org/tutorials.html>`_.
86 Note that even if most of these examples are from the same individual, several people in the team can present the project.
87 It's just that I wrote this paragraph so took the examples I knew, from my own experience :)
89 Report (and fix) issues
90 ^^^^^^^^^^^^^^^^^^^^^^^
92 Because of its size and complexity, SimGrid far from perfect and
93 contains a large amount of glitches and issues. When you find one,
94 don't assume that it's here because we don't care. It survived only
95 because nobody told us. We unfortunately cannot endlessly review our
96 large code and documentation base. So please, **report any issue you
97 find**, be it a typo in the documentation, a paragraph that needs to
98 be reworded, a bug in the code, or any other problem. The best way to
99 do so is to open an issue on our
100 `Bug Tracker <https://framagit.org/simgrid/simgrid/issues>`_ so
101 that we don't forget about it.
103 The worst way to report such issues is to go through private emails.
104 These are unreliable, and we are trying to develop SimGrid openly, so
105 private discussions are to be avoided if possible.
107 If you can provide a patch fixing the issue you report, that's even
108 better. If you cannot, then you need to give us a minimal working
109 example (MWE), that is a ready to use solution that reproduces the
110 problem you face. Your bug will take much more time
111 for us to reproduce and fix if you don't give us the MWE, so you want
112 to help us helping you to get things efficient.
114 Of course, a very good way to give back to the SimGrid community is to
115 triage and fix the bugs in the Bug Tracking Systems. If the bug report
116 has no MWE, we'd love you to contribute one. If you can come up with a
117 patch, we will be more than happy to apply your changes so that the
118 whole community enjoys them.
120 Extending SimGrid and its Ecosystem
121 -----------------------------------
126 If you deeply miss a feature in the framework, you should consider
127 implementing it yourself. SimGrid is free software, meaning that you are
128 free to help yourself. Of course, we'll do our best to assist you in
129 this task, so don't hesitate to contact us with your idea.
131 You could write a new plugin extending SimGrid in some way, or a
132 routing model for another kind of network. But even if you write your own
133 platform file, this is probably interesting to other users too, and
134 could be included to SimGrid. Modeling accurately a given platform is
135 a difficult work, which outcome is very precious to us.
137 Or maybe you developed an independent tool on top of SimGrid. We'd
138 love helping you gaining visibility by listing it in our
139 `Contrib <https://simgrid.org/contrib.html>`_.
141 Possible Enhancements
142 ^^^^^^^^^^^^^^^^^^^^^
144 If you want to start working on the SimGrid codebase, here are a few
145 ideas of things that could be done to improve the current code (not all of them
146 are difficult, do trust yourself ;)
151 We should avoir using "-1" to mean "forever" at least in S4U and in
152 the internal code. We should probably always use separate functions
153 (`wait` vs `wait_for`).
158 - Some features are missing in the Maestro future implementation
159 (`simgrid::kernel::Future`, `simgrid::kernel::Promise`)
160 could be extended to support additional features:
161 `when_any`, `shared_future`, etc.
163 - The corresponding feature might then be implemented in the user process
164 futures (`simgrid::simix::Future`).
166 - Currently `.then()` is not available for user futures. We would need to add
167 a basic user event loop in order to queue the pending continuations.
169 - We might need to provide an option to cancel a pending operation. This
170 might be achieved by defining some `Action` or `Operation` class with an
171 API compatible with `Future` (and convertible to it) but with an
172 additional `.cancel()` method.
174 MC: Overhaul the state comparison code
175 """"""""""""""""""""""""""""""""""""""
177 The state comparison code is quite complicated. It has very long functions and
178 is programmed mostly using C idioms and is difficult to understand and debug.
179 It is in need of an overhaul:
181 - cleanup, refactoring, usage of C++ features.
183 - The state comparison code works by inferring types of blocks allocated on the
184 heap by following pointers from known roots (global variables, local
185 variables). Usually the first type found for a given block is used even if
186 a better one could be found later. By using a first pass of type inference,
187 on each snapshot before comparing the states, we might use a better type
188 information on the different blocks.
190 - We might benefit from adding logic for handling some known types. For
191 example, both `std::string` and `std::vector` have a capacity which might
192 be larger than the current size of the container. We should ignore
193 the corresponding elements when comparing the states and inferring the types.
195 - Another difficulty in the state comparison code is the detection of
196 dangling pointers. We cannot easily know if a pointer is dangling and
197 dangling pointers might lead us to choose the wrong type when inferring
198 heap blocks. We might mitigate this problem by delaying the reallocation of
199 a freed block until there is no blocks pointing to it anymore using some
200 sort of basic garbage-collector.
202 MC: Hashing the states
203 """"""""""""""""""""""
205 In order to speed up the state comparison an idea was to create a hash of the
206 state. Only states with the same hash would need to be compared using the
207 state comparison algorithm. Some information should not be included in the
208 hash in order to avoid considering different states which would otherwise
209 would have been considered equal.
211 The states could be indexed by their hash. Currently they are indexed
212 by the number of processes and the amount of heap currently allocated
213 (see `DerefAndCompareByNbProcessesAndUsedHeap`).
215 Good candidate information for the state hashing:
217 - number of processes;
219 - their backtraces (instruction addresses);
221 - their current simcall numbers;
223 - some simcall arguments (eg. number of elements in a waitany);
225 - number of pending communications;
229 Some basic infrastructure for this is already in the code (see `mc_hash.cpp`)
230 but it is currently disabled.
232 Interface with the model-checked processes
233 """"""""""""""""""""""""""""""""""""""""""
235 The model checker reads many information about the model-checked process by
236 `process_vm_readv()`-ing brutally the data structure of the model-checked
237 process leading to some inefficient code such as maintaining copies of complex
238 C++ structures in XBT dynars. We need a sane way to expose the relevant
239 information to the model checker.
244 We have introduced some generic simcalls which can be used to execute a
245 callback in a SimGrid Maestro context. It makes it a lot easier to interface
246 the simulated process with the maestro. However, the callbacks for the
247 model checker which cannot decide how it should handle them. We would need a
248 solution for this if we want to be able to replace the simcalls the
249 model checker cares about by generic simcalls.
251 Defining an API for writing Model-Checking algorithms
252 """""""""""""""""""""""""""""""""""""""""""""""""""""
254 Currently, writing a new model-checking algorithms in SimGridMC is quite
255 difficult: the logic of the model-checking algorithm is mixed with a lot of
256 low-level concerns about the way the model checker is implemented. This makes it
257 difficult to write new algorithms and difficult to understand, debug, and modify
258 the existing ones. We need a clean API to express the model-checking algorithms
259 in a form which is closer to the text-book/paper description. This API must
260 be exposed in a language which is more adequate to this task.
264 1. Design and implement a clean API to express model-checking algorithms.
265 A `Session` class currently exists for this but is not feature complete
266 and should probably be rewritten. It should be easy to create bindings
267 for different languages on top of this API.
269 2. Create a binding to some better suited, dynamic, scripting language
272 3. Rewrite the existing model-checking algorithms in this language using the
