Update the 5 min intro

Author: olivhoenen

docs/source/intro.rst

@@ -20,11 +20,11 @@ be outdated.
 
     >>> import imas
     >>> print(imas.__version__)
-    1.0.0
+    2.0.0
 
 .. note::
 
-    If you have an IMAS-Python install without the IMAS Access Layer, importing
+    If you have an IMAS-Python install without the IMAS-Core, importing
     IMAS-Python will display an error message. You can still use IMAS-Python, but not all
     functionalities are available.
 
@@ -44,7 +44,7 @@ on different Data Dictionary versions.
     >>> import imas
     >>> import numpy as np
     >>> ids_factory = imas.IDSFactory()
-    13:26:47 [INFO] Parsing data dictionary version 3.38.1 @dd_zip.py:127
+    18:23:12 INFO Parsing data dictionary version 4.0.0 @dd_zip.py:166
     >>> # Create an empty core_profiles IDS
     >>> core_profiles = ids_factory.core_profiles()
 
@@ -56,6 +56,7 @@ We can now use this ``core_profiles`` IDS and assign some data to it:
     >>> core_profiles.ids_properties.homogeneous_time = imas.ids_defs.IDS_TIME_MODE_HOMOGENEOUS
     >>> # array quantities are automatically converted to the appropriate numpy arrays
     >>> core_profiles.time = [1, 2, 3]
+    18:24:58 INFO     Assigning incorrect type 'int64' to <IDSNumericArray (IDS:core_profiles, time, empty FLT_1D)>, attempting automatic conversion. @ids_primitive.py:483
     >>> # the python list of ints is converted to a 1D array of floats
     >>> core_profiles.time
     <IDSNumericArray (IDS:core_profiles, time, FLT_1D)>
@@ -66,7 +67,7 @@ We can now use this ``core_profiles`` IDS and assign some data to it:
     3
     >>> # assign some data for the first time slice
     >>> core_profiles.profiles_1d[0].grid.rho_tor_norm = [0, 0.5, 1.0]
-    >>> core_profiles.profiles_1d[0].j_tor = [0, 0, 0]
+    >>> core_profiles.profiles_1d[0].j_phi = [0., 0., 0.]
 
 As you can see in the example above, IMAS-Python automatically checks the data you try to
 assign to an IDS with the data type specified in the Data Dictionary. When
@@ -77,63 +78,77 @@ get an error message if this is not possible:
 
     >>> core_profiles.time = "Cannot be converted"
     ValueError: could not convert string to float: 'Cannot be converted'
-    >>> core_profiles.time = 1-1j
-    TypeError: can't convert complex to float
-    >>> core_profiles.ids_properties.source = 1-1j  # automatically converted to str
-    >>> core_profiles.ids_properties.source.value
-    '(1-1j)'
+    >>> core_profiles.ids_properties.comment = 1-1j  # automatically converted to str
+    >>> core_profiles.ids_properties.comment
+    str('(1-1j)')
 
 
-Store an IDS to disk
-''''''''''''''''''''
+Load and store an IDS to disk with IMAS-Core
+''''''''''''''''''''''''''''''''''''''''''''
 
 .. note::
 
-    - This functionality requires the IMAS Access Layer.
-    - This API will change when IMAS-Python is moving to Access Layer 5 (expected Q2
-      2023).
+    - This functionality requires the IMAS-Core, until this library is openly available
+      on GitHub you may need to fetch it from `git.iter.org <https://git.iter.org/>`_
+      (requires to have an ITER account). Using IMAS-Core also enable slicing methods
+      :py:meth:`~imas.db_entry.DBEntry.get_slice`, 
+      :py:meth:`~imas.db_entry.DBEntry.put_slice` and
+      :py:meth:`~imas.db_entry.DBEntry.get_sample` (with IMAS-Core>=5.4).
+    - If you can't have access to it, you can save IDS to disk with the built-in
+      netCDF backend :ref:`Store and load an IDS to disk with netCDF`
 
-To store an IDS to disk, we need to indicate the following information to the
-IMAS Access Layer. Please check the `IMAS Access Layer documentation
-<https://imas.iter.org/>`_ for more information on this.
+To store an IDS to disk, we need to indicate the following URI to the
+IMAS-Core: ``imas:<backend>?path=<path_to_folder>`` or using the legacy query keys
+``imas:<backend>?user=<user>;database=<database>;version=<version>;pulse=<pulse>;run=<run>``
+which are then converted as a path ``~user/public/imasdb/database/version/pulse/run``.
 
-- Which backend to use (e.g. MDSPLUS or HDF5)
-- ``tokamak`` (also known as database)
-- ``pulse``
-- ``run``
+Available ``<backend>`` may depend on your IMAS-Core install: ``hdf5``, ``mdsplus``,
+``ascii``, ``memory``, ``uda``.
 
 In IMAS-Python you do this as follows:
 
 .. code-block:: python
 
     >>> # Create a new IMAS data entry for storing the core_profiles IDS we created earlier
     >>> # Here we specify the backend, database, pulse and run
-    >>> dbentry = imas.DBEntry(imas.ids_defs.HDF5_BACKEND, "TEST", 10, 2)
-    >>> dbentry.create()
+    >>> dbentry = imas.DBEntry("imas:hdf5?path=./testdb","w")
     >>> # now store the core_profiles IDS we just populated
     >>> dbentry.put(core_profiles)
 
 .. image:: imas_structure.png
 
+To load an IDS from disk, you need to specify the same information as
+when storing the IDS (see above). Once the data entry is opened, you
+can use ``<IDS>.get()`` to load IDS data from disk: 
 
-Load an IDS from disk
-'''''''''''''''''''''
+.. code-block:: python
 
-.. note::
+    >>> # Now load the core_profiles IDS back from disk
+    >>> dbentry2 = imas.DBEntry("imas:hdf5?path=./testdb","r")
+    >>> core_profiles2 = dbentry2.get("core_profiles")
+    >>> print(core_profiles2.ids_properties.comment.value)
 
-    - This functionality requires the IMAS Access Layer.
-    - This API will change when IMAS-Python is moving to Access Layer 5 (expected Q2
-      2023).
 
-To load an IDS from disk, you need to specify the same information as
-when storing the IDS (see previous section). Once a data entry is opened, you
+Load and store an IDS to disk with IMAS-Core
+''''''''''''''''''''''''''''''''''''''''''''
+
+In IMAS-Python you do this as follows:
+
+.. code-block:: python
+
+    >>> # Create a new IMAS data entry for storing the core_profiles IDS we created earlier
+    >>> # here we directly point to a .nc filename in your system
+    >>> dbentry = imas.DBEntry("mypulsefile.nc","w")
+    >>> # now store the core_profiles IDS we just populated
+    >>> dbentry.put(core_profiles)
+
+To load an IDS from disk, you need to specify the same file information as
+when storing the IDS. Once the data entry is opened, you
 can use ``<IDS>.get()`` to load IDS data from disk: 
 
 .. code-block:: python
 
     >>> # Now load the core_profiles IDS back from disk
-    >>> dbentry2 = imas.DBEntry(imas.ids_defs.HDF5_BACKEND, "TEST", 10, 2)
-    >>> dbentry2.open()
+    >>> dbentry2 = imas.DBEntry("mypulsefile.nc","r")
     >>> core_profiles2 = dbentry2.get("core_profiles")
     >>> print(core_profiles2.ids_properties.comment.value)
-    Testing IMAS-Python