From: Martin Quinson Date: Sat, 21 Jan 2023 16:24:38 +0000 (+0100) Subject: Various fixups and cosmetics in the doc X-Git-Tag: v3.34~607 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/bf58a2961f376ffa8fcad1c2058f7366a747c7cf Various fixups and cosmetics in the doc --- diff --git a/MANIFEST.in b/MANIFEST.in index 3f99337fa5..4cc016d37a 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1642,9 +1642,9 @@ include docs/manpages/tesh.pod include docs/requirements.txt include docs/source/Calibrating_the_models.rst include docs/source/Configuring_SimGrid.rst +include docs/source/Contributors_Documentation.rst include docs/source/Deploying_your_application.rst include docs/source/Design_goals.rst -include docs/source/Developers_Documentation.rst include docs/source/Doxyfile include docs/source/Experimental_setup.rst include docs/source/Installing_SimGrid.rst @@ -1703,6 +1703,8 @@ include docs/source/tuto_disk/fig/griffon_write_dhist.png include docs/source/tuto_disk/fig/simgrid_results.png include docs/source/tuto_disk/init.el include docs/source/tuto_disk/tuto_disk.cpp +include docs/source/tuto_mc/ndet-receive-mpi.c +include docs/source/tuto_mc/ndet-receive-s4u.cpp include docs/source/tuto_network_calibration/CMakeLists.txt include docs/source/tuto_network_calibration/Dockerfile include docs/source/tuto_network_calibration/Utils.cpp diff --git a/docs/source/Configuring_SimGrid.rst b/docs/source/Configuring_SimGrid.rst index bce26b17ec..c6b949444c 100644 --- a/docs/source/Configuring_SimGrid.rst +++ b/docs/source/Configuring_SimGrid.rst @@ -228,7 +228,7 @@ models for all existing resources. `_. - **ns-3** (only available if you compiled SimGrid accordingly): Use the packet-level network - simulators as network models (see :ref:`model_ns3`). + simulators as network models (see :ref:`models_ns3`). This model can be :ref:`further configured `. - ``cpu/model``: specify the used CPU model. We have only one model diff --git a/docs/source/Developers_Documentation.rst b/docs/source/Contributors_Documentation.rst similarity index 98% rename from docs/source/Developers_Documentation.rst rename to docs/source/Contributors_Documentation.rst index 8aac1ef332..f5d3447644 100644 --- a/docs/source/Developers_Documentation.rst +++ b/docs/source/Contributors_Documentation.rst @@ -1,10 +1,10 @@ -.. _dev_doc: +.. _contrib_doc: -Developer's Documentation -========================= +Contributor's Documentation +=========================== -This page describes the software infrastructure for SimGrid potential contributors. This page is particularly interesting if you plan to contribute to the -project. +This page describes the software infrastructure for SimGrid potential contributors. It is particularly interesting if you plan to send some patches for +inclusion in the project code. Enforcing the coding standards ------------------------------ diff --git a/docs/source/Models.rst b/docs/source/Models.rst index 1b4c08a6c6..1055c54d3f 100644 --- a/docs/source/Models.rst +++ b/docs/source/Models.rst @@ -144,6 +144,7 @@ one (10Gb/s) or the one induced by the TCP window, depending on the latency. - If the link latency is 0.001s, :math:`\frac{gamma}{2\times lat}=2,097,152,000 \approx 2Gib/s`, which is smalled than the physical bandwidth. The communication thus fails to fully use the link, and takes about 4.77s. - With a link latency of 0.1s, :math:`gamma/2\times lat \approx 21Mb/s`, so the communication takes about 476.84 + 0.1 seconds! + - More cases are tested and enforced by the test ``teshsuite/models/cm02-tcpgamma/cm02-tcpgamma.tesh`` For more details, please refer to "A Network Model for Simulation of Grid Application" by Henri Casanova and Loris Marchal (published in 2002, thus the model name). diff --git a/docs/source/Release_Notes.rst b/docs/source/Release_Notes.rst index 3d61282c92..998e7624fa 100644 --- a/docs/source/Release_Notes.rst +++ b/docs/source/Release_Notes.rst @@ -571,8 +571,6 @@ stochastic generator of external load has been reintroduced. Version 3.33 (not released yet) ------------------------------- -.. |br| raw:: html - **On the maintainance front,** we removed the ancient MSG interface which end-of-life was scheduled for 2020, the Java bindings that was MSG-only and support for native builds on Windows (WSL is now required). Keeping SimGrid alive while adding new features require to remove old, unused stuff. The very rare users impacted by these removals are urged to @@ -596,4 +594,7 @@ and done! A single activity mixing I/Os and communications can be created whose function (which also derives from the ptask model). The user can specify a ``src_disk`` on a ``src_host`` and a ``dst_disk`` on a ``dst_host`` to stream data of a given ``size``. Note that disks are optional, allowing users to simulate some kind of "disk-to-memory" or "memory-to-disk" I/O streams. + +.. |br| raw:: html +
diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst index 7cf77734df..4d6048907a 100644 --- a/docs/source/Tutorial_Algorithms.rst +++ b/docs/source/Tutorial_Algorithms.rst @@ -550,8 +550,6 @@ is a better way to visualize SimGrid traces (see below). .. image:: /tuto_s4u/img/vite-screenshot.png :align: center -.. note:: - If you want the full power to visualize SimGrid traces, you need to use R. As a start, you can download this `starter script `_ diff --git a/docs/source/XML_reference.rst b/docs/source/XML_reference.rst index 2124a83d54..7514d0e798 100644 --- a/docs/source/XML_reference.rst +++ b/docs/source/XML_reference.rst @@ -193,13 +193,13 @@ We provide an example model of file system as a plugin, (sparsely) documented in A host is the computing resource on which an actor can run. See :cpp:class:`simgrid::s4u::Host`. **Parent tags:** :ref:`pf_tag_zone` (only leaf zones, i.e., zones containing neither inner zones nor clusters) |br| -**Children tags:** :ref:`pf_tag_mount`, :ref:`pf_tag_prop`, :ref:`pf_tag_disk` |br| +**Children tags:** :ref:`pf_tag_prop`, :ref:`pf_tag_disk` |br| **Attributes:** :``id``: Host name. Must be unique over the whole platform. :``speed``: Computational power (per core, in flop/s). - If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`). + If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`API_s4u_Host_dvfs`). :``core``: Amount of cores (default: 1). See :ref:`howto_multicore`. :``availability_file``: @@ -247,7 +247,7 @@ A host is the computing resource on which an actor can run. See :cpp:class:`simg :``coordinates``: Vivaldi coordinates (meaningful for Vivaldi zones only). See :ref:`pf_tag_peer`. :``pstate``: Initial pstate (default: 0, the first one). - See :ref:`howto_dvfs`. + See :ref:`API_s4u_Host_dvfs`. ------------------------------------------------------------------------------- @@ -400,7 +400,7 @@ and a download link. :``id``: Name of the host. Must be unique on the whole platform. :``speed``: Computational power (in flop/s). - If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`). + If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`API_s4u_Host_dvfs`). :``bw_in``: Bandwidth of the private downstream link, along with its unit. See :ref:`pf_tag_link`. :``bw_out``: Bandwidth of the private upstream link, along with its diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 5408491ea1..ff3a4f3e68 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -1395,9 +1395,13 @@ On/Off .. doxygenfunction:: sg_host_turn_off(sg_host_t host) .. doxygenfunction:: sg_host_turn_on(sg_host_t host) +.. _API_s4u_Host_dvfs: + DVFS ---- +See also the :ref:`relevant examples `. + .. tabs:: .. group-tab:: C++ @@ -2208,11 +2212,12 @@ Querying info .. automethod:: simgrid.Comm.set_payload_size .. automethod:: simgrid.Comm.set_rate -Life cycle ----------- +Direct host-to-host communication +--------------------------------- Most communications are created using :ref:`s4u_mailbox`, but you can -also start direct communications as shown below. +also start direct communications as shown below. See also the +:ref:`relevant examples `. .. tabs:: @@ -2223,6 +2228,19 @@ also start direct communications as shown below. .. doxygenfunction:: simgrid::s4u::Comm::sendto_init(Host *from, Host *to) .. doxygenfunction:: simgrid::s4u::Comm::sendto_async + .. group-tab:: Python + + .. automethod:: simgrid.Comm.sendto + .. automethod:: simgrid.Comm.sendto_init + .. automethod:: simgrid.Comm.sendto_async + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Comm::cancel .. doxygenfunction:: simgrid::s4u::Comm::start .. doxygenfunction:: simgrid::s4u::Comm::test @@ -2237,10 +2255,6 @@ also start direct communications as shown below. .. group-tab:: Python - .. automethod:: simgrid.Comm.sendto - .. automethod:: simgrid.Comm.sendto_init - .. automethod:: simgrid.Comm.sendto_async - .. automethod:: simgrid.Comm.cancel .. automethod:: simgrid.Comm.start .. automethod:: simgrid.Comm.test diff --git a/docs/source/app_smpi.rst b/docs/source/app_smpi.rst index 24f8bf73ae..ddea04e9ef 100644 --- a/docs/source/app_smpi.rst +++ b/docs/source/app_smpi.rst @@ -106,7 +106,7 @@ tracing during the simulation. You can get the full list by running Finally, you can pass :ref:`any valid SimGrid parameter ` to your program. In particular, you can pass ``--cfg=network/model:ns-3`` to -switch to use :ref:`model_ns3`. These parameters should be placed after +switch to use :ref:`models_ns3`. These parameters should be placed after the name of your binary on the command line. ............................... diff --git a/docs/source/conf.py b/docs/source/conf.py index aba1bc4ed3..1c8d99c369 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -176,7 +176,7 @@ master_doc = 'index' # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/source/index.rst b/docs/source/index.rst index 4d20670901..f696feb01a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -94,7 +94,7 @@ of every page. Bugs in the code should be reported :caption: SimGrid's Internals: Design goals - Developer's documentation + Contributor's documentation .. Cheat Sheet on the sublevels .. diff --git a/docs/source/tuto_mc/ndet-receive-mpi.c b/docs/source/tuto_mc/ndet-receive-mpi.c new file mode 100644 index 0000000000..4123ab9809 --- /dev/null +++ b/docs/source/tuto_mc/ndet-receive-mpi.c @@ -0,0 +1,54 @@ +/* Copyright (c) 2010-2021. The SimGrid Team. All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + +/******************** Non-deterministic message ordering *********************/ +/* Server assumes a fixed order in the reception of messages from its clients */ +/* which is incorrect because the message ordering is non-deterministic */ +/******************************************************************************/ + +#include + +int main(int argc, char **argv) +{ + int size; + int rank; + MPI_Status status; + + /* Initialize MPI */ + int err = MPI_Init(&argc, &argv); + if (err != MPI_SUCCESS) { + printf("MPI initialization failed!\n"); + exit(1); + } + + MPI_Comm_size(MPI_COMM_WORLD, &size); /* Get nr of tasks */ + MPI_Comm_rank(MPI_COMM_WORLD, &rank); /* Get id of this process */ + if (size != 4) { + printf("run this program with exactly 4 processes (-np 4)\n"); + MPI_Finalize(); + exit(0); + } + + if (rank == 0) { + int recv_buffer; + for (int i = 0; i < size - 1; i++) { + MPI_Recv(&recv_buffer, 1, MPI_INT, MPI_ANY_SOURCE, MPI_ANY_TAG, MPI_COMM_WORLD, &status); + printf("Message received from %d\n", recv_buffer); + } + + if (recv_buffer != 3) { + printf("The last received message is not 3 but %d!\n", recv_buffer); + fflush(stdout); + abort(); + } + }else{ + MPI_Send(&rank, 1, MPI_INT, 0, 42, MPI_COMM_WORLD); + printf("Sent %d to rank 0\n", rank); + } + + MPI_Finalize(); + + return 0; +} diff --git a/docs/source/tuto_mc/ndet-receive-s4u.cpp b/docs/source/tuto_mc/ndet-receive-s4u.cpp new file mode 100644 index 0000000000..061ae71250 --- /dev/null +++ b/docs/source/tuto_mc/ndet-receive-s4u.cpp @@ -0,0 +1,56 @@ +/* Copyright (c) 2010-2021. The SimGrid Team. All rights reserved. */ + +/* This program is free software; you can redistribute it and/or modify it + * under the terms of the license (GNU LGPL) which comes with this package. */ + +/******************** Non-deterministic message ordering *********************/ +/* Server assumes a fixed order in the reception of messages from its clients */ +/* which is incorrect because the message ordering is non-deterministic */ +/******************************************************************************/ + +#include +namespace sg4 = simgrid::s4u; + +constexpr int N = 3; + +XBT_LOG_NEW_DEFAULT_CATEGORY(example, "this example"); + +static void server() +{ + auto mb = sg4::Mailbox::by_name("mymailbox"); + int value_got = -1; + for (int count = 0; count < N; count++) { + int *received = mb->get(); + value_got = *received; + delete received; + } + xbt_assert(value_got == 3); + + XBT_INFO("OK"); +} + +static void client(int id) +{ + auto* payload = new int(id); + XBT_INFO("Sending %d", id); + sg4::Mailbox::by_name("mymailbox")->put(payload, 10000); + XBT_INFO("Sent!"); +} + +int main(int argc, char* argv[]) +{ + sg4::Engine e(&argc, argv); + + std::string platform_file = "small_platform.xml"; + if (argc > 1) + platform_file = argv[1]; + e.load_platform(platform_file); + + sg4::Actor::create("server", sg4::Host::by_name("Tremblay"), server); + sg4::Actor::create("client", sg4::Host::by_name("Jupiter"), client, 1); + sg4::Actor::create("client", sg4::Host::by_name("Bourassa"), client, 2); + sg4::Actor::create("client", sg4::Host::by_name("Ginette"), client, 3); + + e.run(); + return 0; +} diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 034fb28547..68e09a5a41 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -805,7 +805,7 @@ set(DOC_SOURCES docs/source/community.rst docs/source/Configuring_SimGrid.rst docs/source/Deploying_your_application.rst - docs/source/Developers_Documentation.rst + docs/source/Contributors_Documentation.rst docs/source/Experimental_setup.rst docs/source/index.rst docs/source/intl.rst @@ -850,6 +850,9 @@ set(DOC_SOURCES docs/source/tuto_smpi/gemm_mpi.cpp docs/source/tuto_smpi/roundtrip.c + docs/source/tuto_mc/ndet-receive-mpi.c + docs/source/tuto_mc/ndet-receive-s4u.cpp + docs/source/tuto_disk/analysis.org docs/source/tuto_disk/analysis.irst docs/source/tuto_disk/CMakeLists.txt