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