From ff1aaab0aa27803e6bf7c1664c14435fbd17bb76 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Tue, 28 May 2019 11:02:13 +0200 Subject: [PATCH] Reorder code in documentation (first C++, then Python) --- doc/source/users/user_manual/modules/fits/create.rst | 42 +++++++++++++++++++++--------------------- doc/source/users/user_manual/modules/obs/caldb.rst | 32 +++++++++++++++----------------- doc/source/users/user_manual/modules/obs/energy.rst | 48 ++++++++++++++++++++++-------------------------- doc/source/users/user_manual/modules/obs/xml.rst | 56 +++++++++++++++++++++++++------------------------------- doc/source/users/user_manual/modules/support/interpolation.rst | 27 ++++++++++++++------------- doc/source/users/user_manual/modules/support/media.rst | 24 ++++++++++++------------ doc/source/users/user_manual/modules/support/random.rst | 34 +++++++++++++++++----------------- 7 files changed, 126 insertions(+), 137 deletions(-) diff --git a/doc/source/users/user_manual/modules/fits/create.rst b/doc/source/users/user_manual/modules/fits/create.rst index bc9d06f..287c3ef 100644 --- a/doc/source/users/user_manual/modules/fits/create.rst +++ b/doc/source/users/user_manual/modules/fits/create.rst @@ -6,27 +6,6 @@ one image and one table (see ``examples/cpp/createfits/createfits.cpp`` for the source code; the line numbers are for reference and are not part of the source code) -**Python** - -.. code-block:: python - :linenos: - - fits = gammalib.GFits() - image = gammalib.GFitsImageDouble(20,10) - for x in range(20): - for y in range(10): - image[x,y] = x+100.0*y - fits.append(image) - table = gammalib.GFitsBinTable() - column = gammalib.GFitsTableDoubleCol('ENERGY', 10, 3) - for row in range(10): - for index in range(3): - column[row, index] = row*100.0+index - table.append(column) - fits.append(table) - fits.saveto('my_fits_file.fits', True) - fits.close() - **C++** .. code-block:: cpp @@ -52,6 +31,27 @@ the source code) fits.saveto("my_fits_file.fits", true); fits.close(); +**Python** + +.. code-block:: python + :linenos: + + fits = gammalib.GFits() + image = gammalib.GFitsImageDouble(20,10) + for x in range(20): + for y in range(10): + image[x,y] = x+100.0*y + fits.append(image) + table = gammalib.GFitsBinTable() + column = gammalib.GFitsTableDoubleCol('ENERGY', 10, 3) + for row in range(10): + for index in range(3): + column[row, index] = row*100.0+index + table.append(column) + fits.append(table) + fits.saveto('my_fits_file.fits', True) + fits.close() + In line 1, a FITS object is allocated in memory. An image is created in line 2, comprising 20 pixels in the x-direction and 10 pixels in the y-direction, each pixel being a double precision diff --git a/doc/source/users/user_manual/modules/obs/caldb.rst b/doc/source/users/user_manual/modules/obs/caldb.rst index 01453d9..f18ab89 100644 --- a/doc/source/users/user_manual/modules/obs/caldb.rst +++ b/doc/source/users/user_manual/modules/obs/caldb.rst @@ -11,37 +11,28 @@ The database is the open by specifying a mission and an instrument name. The examples below show two variants of opening the ``prod2`` database for ``CTA``. -**Python** - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - caldb1 = gammalib.GCaldb('cta','prod2') # Using opening constructor - caldb2 = gammalib.GCaldb() - caldb2.open('cta','prod2') # Using open method - **C++** .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GCaldb caldb1("cta","prod2"); // Using opening constructor GCaldb caldb2; caldb2.open("cta","prod2"); // Using open method -Once opened, the database can be used to locate for example the filename -of a response component. The examples below show how the effective area -filename for the response ``South_5h`` is accessed via the calibration -database. - **Python** .. code-block:: python :linenos: - filename = caldb1.filename('','','EFF_AREA','','','NAME(South_5h)') + caldb1 = gammalib.GCaldb('cta','prod2') # Using opening constructor + caldb2 = gammalib.GCaldb() + caldb2.open('cta','prod2') # Using open method + +Once opened, the database can be used to locate for example the filename +of a response component. The examples below show how the effective area +filename for the response ``South_5h`` is accessed via the calibration +database. **C++** @@ -49,3 +40,10 @@ database. :linenos: GFilename filename = caldb1.filename("","","EFF_AREA","","","NAME(South_5h)"); + +**Python** + +.. code-block:: python + :linenos: + + filename = caldb1.filename('','','EFF_AREA','','','NAME(South_5h)') diff --git a/doc/source/users/user_manual/modules/obs/energy.rst b/doc/source/users/user_manual/modules/obs/energy.rst index b69aeca..1fc4dde 100644 --- a/doc/source/users/user_manual/modules/obs/energy.rst +++ b/doc/source/users/user_manual/modules/obs/energy.rst @@ -12,30 +12,28 @@ The code threads below illustrate how an energy of 511 keV can be set using the energy constructor or a dedicated method, and how that energy can be retrieved in units of MeV. -**Python** - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - energy1 = gammalib.GEnergy(511.0,'keV') # Using energy constructor - energy2 = gammalib.GEnergy() - energy2.keV(511.0) # Using keV method - E_MeV1 = energy2('MeV') # Get energy in MeV - E_MeV2 = energy2.MeV() # Another variant to get energy in MeV - **C++** .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GEnergy energy1(511.0,"keV"); // Using energy constructor GEnergy energy2; energy2.keV(511.0); // Using keV method double E_MeV1 = energy2("MeV"); // Get energy in MeV double E_MeV2 = energy2.MeV(); // Another variant to get energy in MeV +**Python** + +.. code-block:: python + :linenos: + + energy1 = gammalib.GEnergy(511.0,'keV') # Using energy constructor + energy2 = gammalib.GEnergy() + energy2.keV(511.0) # Using keV method + E_MeV1 = energy2('MeV') # Get energy in MeV + E_MeV2 = energy2.MeV() # Another variant to get energy in MeV + Energies can be added and subtracted, or multiplied or divided by a floating point value. In addition, two energies can be divided, resulting in a floating point value. @@ -45,30 +43,28 @@ Energies can be collected by the :doxy:`GEnergies` container class. The threads below illustrate how energies can be appended or inserted into the :doxy:`GEnergies` container class. -**Python** - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - energy1 = gammalib.GEnergy(511.0,'keV') # Set first energy - energy2 = gammalib.GEnergy(1024.0,'keV') # Set second energy - energies = gammalib.GEnergies() # Create energy container instance - energies.append(energy1) # Append first energy - energies.insert(0,energy2) # Insert second energy before first energy - **C++** .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GEnergy energy1(511.0,"keV"); // Set first energy GEnergy energy2(1024.0,"keV"); // Set second energy GEnergies energies; // Create energy container instance energies.append(energy1); // Append first energy energies.insert(0,energy2); // Insert second energy before first energy +**Python** + +.. code-block:: python + :linenos: + + energy1 = gammalib.GEnergy(511.0,'keV') # Set first energy + energy2 = gammalib.GEnergy(1024.0,'keV') # Set second energy + energies = gammalib.GEnergies() # Create energy container instance + energies.append(energy1) # Append first energy + energies.insert(0,energy2) # Insert second energy before first energy + The energy container can be saved into a file using the :doxy:`GEnergies::save()` method, and loaded from a file using either the load constructor or the :doxy:`GEnergies::load()` method. diff --git a/doc/source/users/user_manual/modules/obs/xml.rst b/doc/source/users/user_manual/modules/obs/xml.rst index 7532d35..2a36c4b 100644 --- a/doc/source/users/user_manual/modules/obs/xml.rst +++ b/doc/source/users/user_manual/modules/obs/xml.rst @@ -58,47 +58,17 @@ Similar definitions exist for the other instruments. The code threads below show different variants of how observations can be loaded from or saved into an XML file. -**Python** - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - obs = gammalib.GObservations('my_observations.xml') # Construct observations from XML file - obs.save('my_copied_observations.xml') # Save observations into XML file - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - obs = gammalib.GObservations() # Construct empty observations - obs.load('my_observations.xml') # Load observations from XML file - obs.save('my_copied_observations.xml') # Save observations into XML file - -.. code-block:: python - :linenos: - - import gammalib # Make GammaLib available - obs = gammalib.GObservations() # Construct empty observations - xmlin = gammalib.GXml('my_observations.xml') # Construct GXml instance from XML file - xmlout = gammalib.GXml() # Construct empty GXml instance - obs.read(xmlin) # Read observations from GXml instance - obs.write(xmlout) # Write observations into GXml instance - xmlout.save('my_copied_observations.xml') # Save GXml instance in XML file - **C++** .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GObservations obs("my_observations.xml"); // Construct observations from XML file obs.save("my_copied_observations.xml"); // Save observations into XML file .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GObservations obs; // Construct empty observations obs.load("my_observations.xml"); // Load observations from XML file obs.save("my_copied_observations.xml"); // Save observations into XML file @@ -106,10 +76,34 @@ loaded from or saved into an XML file. .. code-block:: cpp :linenos: - #include "GammaLib.hpp" // Make GammaLib available GObservations obs; // Construct empty observations GXml xmlin("my_observations.xml"); // Construct GXml instance from XML file GXml xmlout; // Construct empty GXml instance obs.read(xmlin); // Read observations from GXml instance obs.write(xmlout); // Write observations into GXml instance xmlout.save("my_copied_observations.xml"); // Save GXml instance in XML file + +**Python** + +.. code-block:: python + :linenos: + + obs = gammalib.GObservations('my_observations.xml') # Construct observations from XML file + obs.save('my_copied_observations.xml') # Save observations into XML file + +.. code-block:: python + :linenos: + + obs = gammalib.GObservations() # Construct empty observations + obs.load('my_observations.xml') # Load observations from XML file + obs.save('my_copied_observations.xml') # Save observations into XML file + +.. code-block:: python + :linenos: + + obs = gammalib.GObservations() # Construct empty observations + xmlin = gammalib.GXml('my_observations.xml') # Construct GXml instance from XML file + xmlout = gammalib.GXml() # Construct empty GXml instance + obs.read(xmlin) # Read observations from GXml instance + obs.write(xmlout) # Write observations into GXml instance + xmlout.save('my_copied_observations.xml') # Save GXml instance in XML file diff --git a/doc/source/users/user_manual/modules/support/interpolation.rst b/doc/source/users/user_manual/modules/support/interpolation.rst index 2050c71..a400291 100644 --- a/doc/source/users/user_manual/modules/support/interpolation.rst +++ b/doc/source/users/user_manual/modules/support/interpolation.rst @@ -7,19 +7,6 @@ used to describe a functional relation :math:`y_i=f(x_i)`. The following code illustrates how the :doxy:`GNodeArray` class is used (see ``examples/cpp/interpolate/interpolate.cpp`` for the source code): -**Python** - -.. code-block:: python - :linenos: - - x_i = [1.0, 4.0, 6.0] - y_i = [8.0, 7.0, 2.0] - nodes = gammalib.GNodeArray(x_i) - for x in range(20): - nodes.set_value(x*0.5) - y = y_i[nodes.inx_left()] * nodes.wgt_left() + y_i[nodes.inx_right()] * nodes.wgt_right() - print('x=%f : y=%f' % (x, y)) - **C++** .. code-block:: cpp @@ -34,6 +21,20 @@ code illustrates how the :doxy:`GNodeArray` class is used std::cout << "x=" << x << " : y=" << y << std::endl; } +**Python** + +.. code-block:: python + :linenos: + + x_i = [1.0, 4.0, 6.0] + y_i = [8.0, 7.0, 2.0] + nodes = gammalib.GNodeArray(x_i) + for x in range(20): + nodes.set_value(x*0.5) + y = y_i[nodes.inx_left()] * nodes.wgt_left() + y_i[nodes.inx_right()] * nodes.wgt_right() + print('x=%f : y=%f' % (x, y)) + + In line 1, the nodes :math:`x_i` at which the function values :math:`y_i` are given are declared, the actual function values :math:`y_i` are declared in line 2. In line 3, a node array is constructed from the diff --git a/doc/source/users/user_manual/modules/support/media.rst b/doc/source/users/user_manual/modules/support/media.rst index 780760b..f089ebd 100644 --- a/doc/source/users/user_manual/modules/support/media.rst +++ b/doc/source/users/user_manual/modules/support/media.rst @@ -14,18 +14,6 @@ media is implemented by the :doxy:`GUrlString` class. An example of a class making using of :doxy:`GUrl` is the :doxy:`GXml` class. Look at the following code: -**Python** - -.. code-block:: python - :linenos: - - xml = gammalib.GXml() - xml.append(gammalib.GXmlElement('dummy')) - file = gammalib.GUrlFile('my_file.xml', 'w') - chain = gammalib.GUrlString() - xml.write(file) - xml.write(chain) - **C++** .. code-block:: cpp @@ -38,6 +26,18 @@ at the following code: xml.write(file); xml.write(chain); +**Python** + +.. code-block:: python + :linenos: + + xml = gammalib.GXml() + xml.append(gammalib.GXmlElement('dummy')) + file = gammalib.GUrlFile('my_file.xml', 'w') + chain = gammalib.GUrlString() + xml.write(file) + xml.write(chain) + Line 1 declares a XML object and in line 2 we append a dummy element to it. In line 3 we now create a file named ``my_file.xml`` for which we allow write access. In line 4 we allocate a string media. We then diff --git a/doc/source/users/user_manual/modules/support/random.rst b/doc/source/users/user_manual/modules/support/random.rst index 4459fa2..d17762a 100644 --- a/doc/source/users/user_manual/modules/support/random.rst +++ b/doc/source/users/user_manual/modules/support/random.rst @@ -4,17 +4,6 @@ Random number generation Random number generation is widely used within GammaLib for drawing event distributions from functions. -**Python** - -.. code-block:: python - :linenos: - - ran = gammalib.GRan() # Construct random number generate instance - uniform = ran.uniform() # Uniform random number - exponential = ran.exp(3.7) # Exponential random number - poisson = ran.poisson(2.4) # Poisson random number - chi2 = ran.chisq2() # Chi2 random number - **C++** .. code-block:: cpp @@ -26,17 +15,20 @@ distributions from functions. double poisson = ran.poisson(2.4); // Poisson random number double chi2 = ran.chisq2(); // Chi2 random number -In line 1 a random number generator is allocated. If control over the -seed value of the random number generator is needed (for example to draw -different samples), you may specify the seed value upon construction: - **Python** .. code-block:: python :linenos: - seed = 123456 - ran = gammalib.GRan(seed) + ran = gammalib.GRan() # Construct random number generate instance + uniform = ran.uniform() # Uniform random number + exponential = ran.exp(3.7) # Exponential random number + poisson = ran.poisson(2.4) # Poisson random number + chi2 = ran.chisq2() # Chi2 random number + +In line 1 a random number generator is allocated. If control over the +seed value of the random number generator is needed (for example to draw +different samples), you may specify the seed value upon construction: **C++** @@ -46,6 +38,14 @@ different samples), you may specify the seed value upon construction: unsigned long long int seed = 123456; GRan ran(seed); +**Python** + +.. code-block:: python + :linenos: + + seed = 123456 + ran = gammalib.GRan(seed) + The :doxy:`GRan::uniform` method returns a random number between 0 and 1. The :doxy:`GRan::exp` method returns a random number of the exponential law -- libgit2 0.21.4