doc/doxygen/module-index.doc

   1 /**
   2 @defgroup XBT_API      XBT: SimGrid core toolbox
   3 @brief The core toolbox of SimGrid, containing useful datatypes and friends
   4 */
   5
   6 /**
   7 @defgroup TRACE_API TRACING
   8 @brief Gather data about your simulation for later analysis
   9
  10 SimGrid can trace the resource (of hosts and links) utilization using
  11 any of its programming interfaces (MSG, SimDAG and SMPI). This means
  12 that the tracing will register how much power is used for each host
  13 and how much bandwidth is used for each link of the platform.
  14
  15 The idea of the tracing facilities is to give SimGrid users to
  16 possibility to classify MSG and SimDAG tasks by category, tracing the
  17 platform utilization (hosts and links) for each of the categories.
  18 The API enables the declaration of categories and a function to
  19 associate them to the tasks (MSG and SD). The tasks that are not
  20 classified according to a category are not traced. If no categories
  21 are specified, simulations can still be traced using a special
  22 parameter in the command line (see @ref outcomes_vizu for details).
  23 */
  24
  25 /** @defgroup ROUTING_API  Routing: Determining the communication paths
  26     @brief Organize the platform to determine the links used by each communication
  27
  28 @section routing_basics Basic Concepts
  29
  30 The purpose of the simgrid::kernel::routing module is to retrieve the
  31 routing path between two points in a time- and space-efficient manner.
  32 Indeed, the network model needs both the list of links that the convey
  33 the created communication, and the summed latency that these links
  34 represent. This operation is clearly on the critical path of most
  35 SimGrid simulations.
  36
  37 When defining how the information is routed in the simulated network,
  38 it is certainly very tempting to use a formalism somehow similar to
  39 how it is defined on real network. One would have to define the
  40 routing tables of each routers interconnections sub-networks, just
  41 like in the real life. Given the daunting amount of configuration
  42 required, we could complete the information given by the user with
  43 classical protocols such as BGP and RIP. Many network simulator take
  44 such configuration as an input, for good reasons.
  45
  46 This is not the way it goes in SimGrid: the network routing is defined
  47 in a global and compact way instead. This eases the modeling of very
  48 large systems, and allows highly optimized datastructures and
  49 algorithms in the simulator. The proposed description mechanism is
  50 thus much more convinient and efficient. In addition, it is more
  51 expressive than the classical solution based on forwarding tables on
  52 each host and router.
  53
  54 The price to pay is that this representation of networks is very
  55 specific to SimGrid, so you will have to read further to understand
  56 it, even if you already know how real networks work.
  57
  58 The central notion here are @b Networking @b Zones. NetZones represent
  59 network areas in which the routing is done in an homogeneous way.
  60 Conceptually, netzones generalize from the ideas of local networks
  61 (such as Ethernet switched networks) and Autonomous System. The
  62 network as a whole is represented as a single hierarchy of netzones,
  63 meaning that every netzone is part of another netzone (but the @c
  64 NetRoot, which is the top-level netzone).
  65
  66 The main goal of the routing module is to provide a list of links
  67 traversed by a given communication and/or a latency to apply. These
  68 information are then used by the network model to compute the time
  69 that this communication takes. This information is retrieved by three
  70 combined algorithms: intra-zone routing, inter-zone routing, and the
  71 bypass mechanism.
  72
  73 The <b>intra-zone level</b> is naturally handled by the netzones. Each
  74 netzone have to specify the routing algorithm it uses for that.
  75 @ref simgrid::kernel::routing::FullZone "FullZone" netzones have complete matrix where matrix(a,b)
  76 represents the full path (the list of links) between the hosts a and
  77 b. @ref simgrid::kernel::routing::FloydZone "FloydZone" apply the Floyd-Warshall algorithm to compute the
  78 paths. @ref simgrid::kernel::routing::ClusterZone "ClusterZone" model classical switched or hub networks,
  79 where each component is connected through a private link onto a common
  80 backbone. Many other routing algorithms are provided to model the
  81 classical needs, but you can naturally define your own routing if the
  82 provided ones do not fit your needs.
  83
  84 The <b>inter-zone algorithm</b> is used when the communication
  85 traverses more than one zone. The overall path goes from the source up
  86 in the netzones' tree, until the first common ancestor zone, and moves
  87 down to the destination. It crawls the differing netzones on its path
  88 according to the user-defined inter-zone routes, moving from gateway
  89 to gateway.
  90
  91 You can also use the <b>bypass mechanism</b> to specify manually some
  92 shortcuts that directly provide the list of links interconnecting two
  93 given processes.
  94
  95 @section routing_declaring Declaring a platform
  96
  97 For now, you can only declare a platform from an XML file, but we are
  98 working to make it possible from the C++ code (or even from bindings
  99 in other languages). Until then, please head to @ref platform.
 100
 101 */
 102
 103 /** @defgroup SIMIX_API      SIMIX
 104     @brief POSIX-like interface for building simulation
 105
 106     This is a developer-level interface that should be useful only if you
 107     plan to design a new interface for SimGrid.
 108 */
 109
 110
 111
 112 /**
 113 @defgroup SURF_API SURF
 114 @brief Internal kernel of all the simulators used in SimGrid, and associated models.
 115
 116 SURF provides the core functionnalities to simulate a virtual
 117 platform. It is very low-level and is not intended to be used by end
 118 users, but rather to serve as a basis for higher-level simulators. Its
 119 interfaces are not frozen (and probably never will be), and the
 120 structure emphasis on performance over ease of use. This module
 121 contains the platform models. If you need a model that is not encoded
 122 yet, please come to the devel mailing list so that we can discuss on
 123 the feasibility of your idea.
 124
 125 Please note that as it is not really intended for public use, this
 126 module is only partially documented.
 127 */
 128
 129
 130