Nuclear Moments, more coding examples

docs/_modules/index.html

@@ -136,6 +136,13 @@
 <li class="toctree-l1"><a class="reference internal" href="../database.html#underlying-databases">2. Underlying databases</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../database.html#data-sources">3. Data sources</a></li>
 </ul>
+<p class="caption" role="heading"><span class="caption-text">The Data API</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../api.html">1. Getting the data from the Web</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api.html#parameters-and-return-formats">2. Parameters and return formats</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api.html#examples">3. Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api.html#deal-with-http-error-403">4. Deal with HTTP Error 403</a></li>
+</ul>
 
 
 

docs/_sources/api.rst.txt

@@ -0,0 +1,132 @@
+.. _api-label:
+
+1. Getting the data from the Web
+--------------------------------
+
+**It** is possible to retrieve NDLab data from the Nuclear Data Section servers using its data API. This might be useful
+in case one does not want to download the NDLab package, or is not using Python.
+
+Here how to construct the request:
+
+::
+
+    https://nds.iaea.org/cgi-bin/ndlab_server.py?fields=<fields list>&filter=<filter to apply>
+
+and here a concrete example to retrive the gamma transition energies and multipolarities of Lithium isotopes
+
+::
+
+    https://nds.iaea.org/cgi-bin/ndlab_server.py?fields=GAMMA.ENERGY,GAMMA.MULTIPOLARITY&filter=GAMMA.NUC.Z=3
+
+The sections of the guide relevant to the API are: 
+
+| :ref:`The Index <index-label>` : gives an overview of NDLab
+| :ref:`The fields parameter <fields-label>` : explains how to construct the **fields** 
+| :ref:`The filter parameter <filter-label>` : for the **filter**
+| :ref:`Examples <retrieve-examples-label>` : provides some cases with explanation, and the 
+| :ref:`Jp values <jp-label>` and :ref:`Decay modes <decaymodes-label>` : gives further details about these fields
+| :ref:`Constructing "Fields" and "Filter" <ndm-label>` : gives the list of fields that can be retireved
+
+:ref:`The Database <database-label>` page explains how the database is constructed, what are the sources, 
+and what are the differences with the `Livechart data API <https://www-nds.iaea.org/relnsd/vcharthtml/api_v0_guide.html>`_
+
+2. Parameters and return formats
+---------------------------------
+
+| **The base** URL of the service is
+| https://nds.iaea.org/cgi-bin/ndlab_server.py?
+
+and accepts the following parametres:
+
+| **fields**, mandatory, see :ref:`The fields parameter <fields-label>`
+| **filter**, optional,  see :ref:`The filter parameter <filter-label>`
+| **return_type**, optional, can be *csv* or *json*. If not specified, the data are returned as csv
+| **action**, optional, can only be *check*, performs a test of the validity of the *fields* and *filter* parameters
+
+3. Examples
+------------
+
+**Any** of the *fields* and *filter* values given in this guide can be passed as parameters, here below some samples: 
+
+* Xe-135 levels in json `[try it] <http://localhost:8123/cgi-bin/ndlab_server.py?fields=LEVEL.ALL&filter=LEVEL.NUC.NUC_ID='135XE'&return_type=json>`_
+
+:: 
+
+    http://localhost:8123/cgi-bin/ndlab_server.py?fields=LEVEL.ALL&filter=LEVEL.NUC.NUC_ID='135XE'&return_type=json
+
+| Remember the *rule 6* of the :ref:`The filter parameter <filter-label>`: 135XE must be between single quotes 
+
+* Ground state properties `[try it] <http://localhost:8123/cgi-bin/ndlab_server.py?fields=LEVEL.HALF_LIFE_SEC,LEVEL.NUC.BINDING_EN,LEVEL.NUC.SN&filter=LEVEL.SEQNO=0>`_ 
+
+:: 
+
+    http://localhost:8123/cgi-bin/ndlab_server.py?fields=LEVEL.HALF_LIFE_SEC,LEVEL.NUC.BINDING_EN,LEVEL.NUC.SN&filter=LEVEL.SEQNO=0
+
+| The ground state is the LEVEL with SEQNO=0. To access the overall properites of the nuclide, use LEVEL.NUC. 
+
+* Auger electrons from the decay of Xe-135 `[try it] <http://localhost:8123/cgi-bin/ndlab_server.py?fields=DR_AUGER.ALL&filter=DR_AUGER.PARENT.NUC_ID='135XE'>`_ 
+
+:: 
+
+    http://localhost:8123/cgi-bin/ndlab_server.py?fields=DR_AUGER.ALL&filter=DR_AUGER.PARENT.NUC_ID='135XE'
+
+* All Xe-135 levels that decay, with decay properties `[try it] <http://localhost:8123/cgi-bin/ndlab_server.py?fields=L_DECAY.LEVEL.ALL,L_DECAY.ALL&filter=L_DECAY.NUC.NUC_ID='135XE'>`_ 
+
+:: 
+
+   http://localhost:8123/cgi-bin/ndlab_server.py?fields=L_DECAY.LEVEL.ALL,L_DECAY.ALL&filter=L_DECAY.NUC.NUC_ID='135XE'
+
+4. Deal with HTTP Error 403
+---------------------------
+
+**There** have been cases in which the service returns an *HTTP Error 403: Forbidden* 
+The workaround is to add an user agent to the request.
+
+Python:
+
+::
+
+    def lc_read_csv(url):
+        req = urllib.request.Request(url)
+        req.add_header('User-Agent', 
+            'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0')
+        content = urllib.request.urlopen(req)
+        return content
+
+Java:
+
+:: 
+
+    protected String lc_read_csv(url){
+
+        URL murl = new URL(url);
+        URLConnection conn = murl.openConnection();
+        conn.setRequestProperty("User-Agent",
+        "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0");
+
+        BufferedReader br = new BufferedReader(
+                    new InputStreamReader(conn.getInputStream()));
+
+        String inputLine;
+        StringBuffer sb = new StringBuffer();
+        while ((inputLine = br.readLine()) != null) {
+            sb.append(inputLine);
+        }
+        br.close();
+        return sb.toString();
+    }
+
+For other languages, add the suggested user agent to the request using the avaliable function
+
+
+
+
+
+
+
+
+
+
+
+
+

docs/_sources/database.rst.txt

@@ -46,18 +46,21 @@ The `RIPL <https://www-nds.iaea.org/RIPL-3/levels/>`_ Discrete Levels database i
 Linking Adopted and Decay datasets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For a given nuclide, the ENSDF database places the evaluated levels and gamma transitions properties in the "Adopted" dataset.
-These are derived by making an overall fit of various "Decay" (and "Reaction") datasets.  
+For a given nuclide, the ENSDF database places the evaluated levels and gamma transitions properties in the "Adopted", which
+are derived by making an overall fit of various "Decay" (and "Reaction") datasets.  
+
 It can happen that the same level, or the same gamma, is present in more than one of these datasets with, for example, an energy slightly different
-in each occurrence. With data scattered in various datasets, and with no easy linking between them, it becames difficult
-for end users to navigate the data.
+in each occurrence. 
+
+With data scattered in various datasets, and with no easy linking between them, it becames difficult
+for users to navigate the data.
 
 Take the following Sm-152 gamma transition as example:
 
 ::
     
-    gamma    start level  end level  dataset
-    energy   energy       energy     category       
+    Gamma    Start level  End level  Dataset
+    energy        energy     energy            
 
     119.46   1082.842     963.358    Adopted Sm-152
 
@@ -67,9 +70,8 @@ Take the following Sm-152 gamma transition as example:
     ....
 
 
-This redundancy is removed in the NDlab database by linking each gamma and level 
-in the "Decay" dataset to the corresponding one in the "Adopted", removing the 
-hurdle of multiple, but different, occurrences of a same entity.
+The NDlab database links each gamma and each level 
+in the "Decay" dataset to the "Adopted" one, removing the multiple, but different, occurrences of a same entity.
 
 .. attention::
 
@@ -81,15 +83,14 @@ hurdle of multiple, but different, occurrences of a same entity.
 
 **When** not otherwise stated, data are from the `ENSDF <https://www.nndc.bnl.gov/ensdf/>`_ database
 
-* Masses and Q-values are from `AME2020 <https://www.anl.gov/phy/atomic-mass-data-resources>`_, published in `Chinese Phys. C 45, 030002 (2021) and Chinese Phys. C 45, 030003 (2021) <https://doi.org/10.1088/1674-1137/abddb0>`_
-* Abundances are from `NUBASE2020 <https://www.anl.gov/phy/atomic-mass-data-resources>`_ published  in `Chinese Phys. C 45, 030001 (2021). <https://doi.org/10.1088/1674-1137/abddae>`_
-* Fission Yields are from Joint Evaluated Fission and Fusion File (JEFF) 3.1.1
-* Charge Radii are from: I.Angeli, K.P. Marinova, *Atomic Data and Nuclear Data Tables* **99** (2013) 69-95 `DOI:10.1016/j.adt.2011.12.006 <http://dx.doi.org/10.1016/j.adt.2011.12.006>`_
-* Atomic radiations, calculated following  `E.Schönfeld, H.Janßen <https://doi.org/10.1016/S0969-8043(99)00216-X>`_ and its references. 
-
-
-
-
-
+* **Masses and Q-values**: `AME2020 <https://www.anl.gov/phy/atomic-mass-data-resources>`_, published in `Chinese Phys. C 45, 030002 (2021) and Chinese Phys. C 45, 030003 (2021) <https://doi.org/10.1088/1674-1137/abddb0>`_
+* **Abundances**: `NUBASE2020 <https://www.anl.gov/phy/atomic-mass-data-resources>`_ published  in `Chinese Phys. C 45, 030001 (2021). <https://doi.org/10.1088/1674-1137/abddae>`_
+* **Fission Yields**: Joint Evaluated Fission and Fusion File (JEFF) 3.1.1
+* **Charge Radii**: I.Angeli, K.P. Marinova, *Atomic Data and Nuclear Data Tables* **99** (2013) 69-95 `DOI:10.1016/j.adt.2011.12.006 <http://dx.doi.org/10.1016/j.adt.2011.12.006>`_
+* **Atomic radiations** calculated following:  `E.Schönfeld, H.Janßen <https://doi.org/10.1016/S0969-8043(99)00216-X>`_ and its references.
+| **Nuclear Moments**: Tables produced by N.J. Stone:
+| Table of Recommended Nuclear Magnetic Dipole Moments: Part I - Long-lived States `indc-nds-0794 <https://nds.iaea.org/publications/indc/indc-nds-0794/>`_, 
+| Table of Recommended Nuclear Magnetic Dipole Moments - Part II, Short-lived States `indc-nds-0816 <https://nds.iaea.org/publications/indc/indc-nds-0816/>`_, 
+| Table of Nuclear Electric Quadrupole Moments `indc-nds-0833 <https://nds.iaea.org/publications/indc/indc-nds-0833/>`_
 
 

docs/_sources/entities.rst.txt

@@ -59,7 +59,7 @@ LEVEL
 | **DIPOLE_MM** |nbspc| |nbspc|  	*(Q)* magnetic dipole moment [Bohr magnetons]
 | **ENERGY** |nbspc| |nbspc|  		*(Q)* level energy [keV]
 | **HALF_LIFE** |nbspc| |nbspc|  	*(Q)* Half-life value as given in the evaluation, see HALF_LIFE_UNITS for the units. Use HALF_LIFE_SEC for calculations 
-| **HALF_LIFE_LIMIT** |nbspc| |nbspc|  	String - > , <, >=, etc..
+| **HALF_LIFE_LIMIT** |nbspc| |nbspc|  	(S) - > , <, >=, etc..
 | **HALF_LIFE_SEC** |nbspc| |nbspc|  	*(Q)* Half-life in [s]
 | **HALF_LIFE_UNITS** |nbspc| |nbspc|  	*(S)* - the Half-life field units
 | **ISOSPIN** |nbspc| |nbspc|  	*(S)* Isospin

docs/_sources/index.rst.txt

@@ -11,11 +11,12 @@
 
       <div style="margin-bottom:30px">&nbsp;</div>
 
+.. _index-label:
 
 Beta Testing User Guide
 =======================
 
-| **NDlab** is a package for nuclear (mainly)structure data analysis, calculation, and modelling. 
+| **NDlab** is a package for nuclear (mainly) structure data analysis, calculation, and modelling. 
 | It caters for users that need to process and navigate the data via software, having no knowledge about the formats and data structures of the original data libraries. 
 
 .. attention::
@@ -47,6 +48,7 @@ Its main features are:
 * customizable Pyhton modules to write algorithms and simulations
 * automatic propagation of uncertainties when performing calculations
 * option to directly access the underlying SQL database
+* option to get the data from Nuclear Data Section's servers using API
 
 
 | In case you wanted to collaborate to the development, you should write
@@ -55,7 +57,7 @@ Its main features are:
 Hands-on tutorial
 -----------------
 
-Besides this documentation, the package comprises ndlab-tutorial.ipynb, a Notebook with live exercises and examples.
+Besides this documentation, in the package you can find ndlab-tutorial.ipynb, a Notebook with live exercises and examples.
 
 You can preview it without installing, look at the static `HTML version <_static/ndlab-tutorial.html>`_ 
 
@@ -101,3 +103,9 @@ Contents
 
    database
 
+.. toctree::
+   :maxdepth: 2
+   :caption: The Data API
+
+   api
+

docs/_sources/installation.rst.txt

@@ -86,13 +86,18 @@ SQLite DB Browser
 5. Change log
 --------------------
 
-Version v.0.1.1.db.0.1.1-beta
+Version v0.1.2.db.0.2.2-beta
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-First test release
+| More robust parsing of the query parameters
 
-Version v.0.1.1.db.0.2.2-beta
+Version v0.1.1.db.0.2.2-beta
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 | The energy and intensities of neutrini emitted by electron capture process where added to the database.
-| See the `ndlab.Dr_nu <code.html#ndlab.Dr_nu>`_  class, and the  `ndlaborm.DR_NU entity <entities.html#dr-nu>`_ 
+| See the `ndlab.Dr_nu <code.html#ndlab.Dr_nu>`_  class, and the  `ndlaborm.DR_NU entity <entities.html#dr-nu>`_ 
+
+Version v0.1.1.db.0.1.1-beta
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First test release

docs/_sources/interrogation.rst.txt

@@ -184,7 +184,17 @@ In the :ref:`ndm reference <ndm-label>`  these fields are flagged with *(Q)*. Qu
     | If you do not want to use the autocompletion, you do not need to import the ndlaborm module.
     | But if ndlaborm was imported using an alias, e.g. :code:`import ndlaborm as no`, when using the autocompletion pay attention not include the alias in the fields variable. :code:`fields = "no.GAMMA.ENERGY"` is not valid, remove the 'no.'.
 
+ .. tip::
+
+    In case of doubt, or unexpected errors, one can use the following two functions 
 
+    ::
+
+        # returns false if there are issues
+        nl.is_query_ok(fields, filter)
+
+        # returns a list with the errors found
+        errors = nl.query_check(fields, filter)
 
 .. _filter-label:
 
@@ -212,6 +222,18 @@ Here below the rules to follow when writing a filter
     * use **in** to filter a set of values, e.g. :code:`NUCLIDE.NUC_ID IN ( '235U', '135XE' )` (notice the single quotes), or :code:`NUCLIDE.Z IN (5, 10)`
     * use **like** to filter the content of a text, e.g. :code:`LEVEL.JP like '%2+%'` will filter the jp values containing the string "2+". See :ref:`jp values <jp-label>` for more
 
+ .. tip::
+
+    In case of doubt, or unexpected errors, one can use the following two functions 
+
+    ::
+
+        # returns false if there are issues
+        nl.is_query_ok(fields, filter)
+
+        # returns a list with the errors found
+        errors = nl.query_check(fields, filter)
+
 .. _retrieve-examples-label:
 
 4. Examples
@@ -249,6 +271,7 @@ Here below the rules to follow when writing a filter
     The ground states properties (Half-life, Jp, etc...) are in the LEVEL, with SEQNO = 0. For example the G.S. of Xe-135 is
     :code:`LEVEL.NUC.NUC_ID = '135XE' and LEVEL.SEQNO = 0`
 
+
 .. _jp-label:
 
 5. J :sup:`p` values
@@ -344,7 +367,7 @@ If you need a unique value, even when the ENSDF evaluation is not unique, then u
 
 
 
-
+.. _decaymodes-label:
 
 6. Decay modes 
 --------------

docs/_static/basic.css

@@ -236,16 +236,6 @@ div.body p, div.body dd, div.body li, div.body blockquote {
 a.headerlink {
     visibility: hidden;
 }
-a.brackets:before,
-span.brackets > a:before{
-    content: "[";
-}
-
-a.brackets:after,
-span.brackets > a:after {
-    content: "]";
-}
-
 
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
@@ -334,11 +324,17 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
+nav.contents,
+aside.topic,
+
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
+nav.contents,
+aside.topic,
+
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -377,13 +373,19 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
+
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
 }
 
 div.sidebar::after,
 aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
+
 div.topic::after,
 div.admonition::after,
 blockquote::after {