docs/source/community.rst

   1 .. _community:
   2
   3 The SimGrid Community
   4 =====================
   5
   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.
  12
  13 Contacting the community
  14 ------------------------
  15
  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.
  21
  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
  31    list.
  32
  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.
  38
  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
  44    guest.
  45
  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.
  52
  53 Giving back to SimGrid
  54 ----------------------
  55
  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.
  58
  59 Spread the word
  60 ^^^^^^^^^^^^^^^
  61
  62 There are many ways to help the SimGrid project. The first and most
  63 natural one is to **use SimGrid for your research, and say so**. Cite
  64 the SimGrid framework in your papers and discuss of its advantages with
  65 your colleagues to spread the word. When we ask for new funding to
  66 sustain the project, the number of publications enabled by SimGrid is
  67 always the first question we get. The more you use the framework,
  68 the better for us.
  69
  70 Make sure that your scientific publications using SimGrid actually
  71 cite the `right paper <https://simgrid.org/publications.html>`_.
  72 Also make sure that these citations are correctly listed on
  73 `our list <https://simgrid.org/usages.html>`_.
  74
  75 You can also **help us constituting an active and welcoming user
  76 community**. Subscribe to the mailing lists, and answer the
  77 questions that newscomers have if you can. Point them (gently ;) to
  78 the relevant part of the documentation on need, and help them becoming
  79 part of our community too.
  80
  81 Another easy way to help the project is to add a link to the `SimGrid
  82 homepage <https://simgrid.org>`_ on your site to improve SimGrid's ranking in
  83 search engines.
  84
  85 Finally, if you organize a scientific event where you expect many
  86 potential users, you can invite us to give a tutorial on SimGrid. We
  87 found that 45 minutes to one hour is very sharp, but
  88 `doable <http://people.irisa.fr/Martin.Quinson/blog/2012/1120/Simgrid_at_Louvain/>`_.
  89 It is enough to explain the main motivations and outcomes of the
  90 project in order to motivate the attendees get more information on
  91 SimGrid, and eventually improve their scientific habits by using a
  92 sound simulation framework.
  93
  94 Report (and fix) issues
  95 ^^^^^^^^^^^^^^^^^^^^^^^
  96
  97 Because of its size and complexity, SimGrid far from perfect and
  98 contains a large amount of glitches and issues. When you find one,
  99 don't assume that it's here because we don't care. It survived only
 100 because nobody told us. We unfortunately cannot endlessly review our
 101 large code and documentation base. So please, **report any issue you
 102 find**, be it a typo in the documentation, a paragraph that needs to
 103 be reworded, a bug in the code, or any other problem. The best way to
 104 do so is to open an issue on our
 105 `Bug Tracker <https://github.com/simgrid/simgrid/issues>`_ so
 106 that we don't forget about it.
 107
 108 The worst way to report such issues is to go through private emails.
 109 These are unreliable, and we are trying to develop SimGrid openly, so
 110 private discussions are to be avoided if possible.
 111
 112 If you can provide a patch fixing the issue you report, that's even
 113 better. If you cannot, then you need to give us a minimal working
 114 example (MWE), that is a ready to use solution that reproduces the
 115 problem you face. Your bug will take much more time
 116 for us to reproduce and fix if you don't give us the MWE, so you want
 117 to help us helping you to get things efficient.
 118
 119 Of course, a very good way to give back to the SimGrid community is to
 120 triage and fix the bugs in the Bug Tracking Systems. If the bug report
 121 has no MWE, we'd love you to contribute one. If you can come up with a
 122 patch, we will be more than happy to apply your changes so that the
 123 whole community enjoys them.
 124
 125 Extending SimGrid and its Ecosystem
 126 -----------------------------------
 127
 128 Contributing Code
 129 ^^^^^^^^^^^^^^^^^
 130
 131 If you deeply miss a feature in the framework, you should consider
 132 implementing it yourself. SimGrid is free software, meaning that you are
 133 free to help yourself. Of course, we'll do our best to assist you in
 134 this task, so don't hesitate to contact us with your idea.
 135
 136 You could write a new plugin extending SimGrid in some way, or a
 137 routing model for another kind of network. But even if you write your own
 138 platform file, this is probably interesting to other users too, and
 139 could be included to SimGrid. Modeling accurately a given platform is
 140 a difficult work, which outcome is very precious to us.
 141
 142 Or maybe you developed an independent tool on top of SimGrid. We'd
 143 love helping you gaining visibility by listing it in our
 144 `Contrib <https://simgrid.org/contrib.html>`_.
 145
 146 Possible Enhancements
 147 ^^^^^^^^^^^^^^^^^^^^^
 148
 149 If you want to start working on the SimGrid codebase, here are a few
 150 ideas of things that could be done to improve the current code (not all of them
 151 are difficult, do trust yourself ;)
 152
 153 Time and duration
 154 """""""""""""""""
 155
 156 We should avoir using "-1" to mean "forever" at least in S4U and in
 157 the internal code.  We should probably always use separate functions
 158 (`wait` vs `wait_for`).
 159
 160 Futures and Promises
 161 """"""""""""""""""""
 162
 163  - Some features are missing in the Maestro future implementation
 164    (`simgrid::kernel::Future`, `simgrid::kernel::Promise`)
 165    could be extended to support additional features:
 166    `when_any`, `shared_future`, etc.
 167
 168  - The corresponding feature might then be implemented in the user process
 169    futures (`simgrid::simix::Future`).
 170
 171  - Currently `.then()` is not available for user futures. We would need to add
 172    a basic user event loop in order to queue the pending continuations.
 173
 174  - We might need to provide an option to cancel a pending operation. This
 175    might be achieved by defining some `Action` or `Operation` class with an
 176    API compatible with `Future` (and convertible to it) but with an
 177    additional `.cancel()` method.
 178
 179 MC: Overhaul the state comparison code
 180 """"""""""""""""""""""""""""""""""""""
 181
 182 The state comparison code is quite complicated. It has very long functions and
 183 is programmed mostly using C idioms and is difficult to understand and debug.
 184 It is in need of an overhaul:
 185
 186   - cleanup, refactoring, usage of C++ features.
 187
 188   - The state comparison code works by inferring types of blocks allocated on the
 189     heap by following pointers from known roots (global variables, local
 190     variables). Usually the first type found for a given block is used even if
 191     a better one could be found later. By using a first pass of type inference,
 192     on each snapshot before comparing the states, we might use a better type
 193     information on the different blocks.
 194
 195   - We might benefit from adding logic for handling some known types. For
 196     example, both `std::string` and `std::vector` have a capacity which might
 197     be larger than the current size of the container. We should ignore
 198     the corresponding elements when comparing the states and inferring the types.
 199
 200   - Another difficulty in the state comparison code is the detection of
 201     dangling pointers. We cannot easily know if a pointer is dangling and
 202     dangling pointers might lead us to choose the wrong type when inferring
 203     heap blocks. We might mitigate this problem by delaying the reallocation of
 204     a freed block until there is no blocks pointing to it anymore using some
 205     sort of basic garbage-collector.
 206
 207 MC: Hashing the states
 208 """"""""""""""""""""""
 209
 210 In order to speed up the state comparison an idea was to create a hash of the
 211 state. Only states with the same hash would need to be compared using the
 212 state comparison algorithm. Some information should not be included in the
 213 hash in order to avoid considering different states which would otherwise
 214 would have been considered equal.
 215
 216 The states could be indexed by their hash. Currently they are indexed
 217 by the number of processes and the amount of heap currently allocated
 218 (see `DerefAndCompareByNbProcessesAndUsedHeap`).
 219
 220 Good candidate information for the state hashing:
 221
 222  - number of processes;
 223
 224  - their backtraces (instruction addresses);
 225
 226  - their current simcall numbers;
 227
 228  - some simcall arguments (eg. number of elements in a waitany);
 229
 230  - number of pending communications;
 231
 232  - etc.
 233
 234 Some basic infrastructure for this is already in the code (see `mc_hash.cpp`)
 235 but it is currently disabled.
 236
 237 Interface with the model-checked processes
 238 """"""""""""""""""""""""""""""""""""""""""
 239
 240 The model checker reads many information about the model-checked process by
 241 `process_vm_readv()`-ing brutally the data structure of the model-checked
 242 process leading to some inefficient code such as maintaining copies of complex
 243 C++ structures in XBT dynars. We need a sane way to expose the relevant
 244 information to the model checker.
 245
 246 Generic simcalls
 247 """"""""""""""""
 248
 249 We have introduced some generic simcalls which can be used to execute a
 250 callback in a SimGrid Maestro context. It makes it a lot easier to interface
 251 the simulated process with the maestro. However, the callbacks for the
 252 model checker which cannot decide how it should handle them. We would need a
 253 solution for this if we want to be able to replace the simcalls the
 254 model checker cares about by generic simcalls.
 255
 256 Defining an API for writing Model-Checking algorithms
 257 """""""""""""""""""""""""""""""""""""""""""""""""""""
 258
 259 Currently, writing a new model-checking algorithms in SimGridMC is quite
 260 difficult: the logic of the model-checking algorithm is mixed with a lot of
 261 low-level concerns about the way the model checker is implemented. This makes it
 262 difficult to write new algorithms and difficult to understand, debug, and modify
 263 the existing ones. We need a clean API to express the model-checking algorithms
 264 in a form which is closer to the text-book/paper description. This API must
 265 be exposed in a language which is more adequate to this task.
 266
 267 Tasks:
 268
 269   1. Design and implement a clean API to express model-checking algorithms.
 270      A `Session` class currently exists for this but is not feature complete
 271      and should probably be rewritten. It should be easy to create bindings
 272      for different languages on top of this API.
 273
 274   2. Create a binding to some better suited, dynamic, scripting language
 275      (e.g., Lua).
 276
 277   3. Rewrite the existing model-checking algorithms in this language using the
 278      new API.