Metadata-Version: 2.1
Name: imaspy
Version: 0.1.1
Summary: Pythonic wrappers for the IMAS Access Layer
Home-page: https://gitlab.com/klimex/imaspy
Author: Karel van de Plassche
Author-email: k.l.vandeplassche@differ.nl
License: UNKNOWN
Description: # IMASPy
        
        IMASPy is (yet another) pure-python library to handle arbitrarily nested
        data structures. IMASPy is designed for, but not necessarily bound to,
        interacting with Interface Data Structures (IDSs) as defined by the
        Integrated Modelling & Analysis Suite (IMAS) Data Model.
        
        It provides:
        * An easy-to-install and easy-to-get started package by
           * Not requiring an IMAS installation
          * Not strictly requiring matching a Data Dictionary (DD) version
        * An pythonic alternative to the IMAS Python High Level Interface (HLI)
        * Checking of correctness on assign time, instead of database write time
        * Dynamically created in-memory pre-filled data trees from DD XML specifications
        
        ## A word of caution
        Development of this package continues under ITER contract at the [ITER bitbucket](https://git.iter.org/projects/IMAS/repos/imaspy). If you are interested in this development, contact the IMAS team on the [IMAS user slack](https://imasusers.slack.com) or open a [JIRA issue](https://jira.iter.org)
        
        ## Documentation
        Documentation is autogenerated from the source using [Sphinx](http://sphinx-doc.org/)
        and can be found at the [gitlab pages](https://klimex.gitlab.io/imaspy/).
        
        ## Getting Started
        
        Clone the repository on your local machine. To set up SSH keys for
        GitLab, look here: https://docs.gitlab.com/ee/ssh/
        ``` bash
        git clone git@gitlab.com:klimex/imaspy.git # Using SSH keys
        git clone https://gitlab.com/klimex/imaspy.git # Using username/password
        ```
        
        Install IMASPy in developer mode with all the optional components it can find:
        ```bash
        cd imaspy
        pip install --user -e .[all]
        ```
        
        For now, let's assume you have a Data Dictionary specification available,
        and managed to compile the AL.
        ``` python
        # Initialize an empty IDS
        import imaspy as imas
        idsdef_dir = <path to IDSDef.xml>
        idsdef = os.path.join(idsdef_dir, 'IDSDef.xml')
        shot = 1234
        run_in = 0
        imas_entry = imas.ids(shot, run_in, xml_path=idsdef, verbosity=2)
        ```
        
        We end up with a `IDSRoot` instance that is pre-filled with all defaults and
        data structures defined in the given DD XML. We could've not given `xml_path`
        to create an empty `IDSRoot`. No interaction with any LL-AL has happened yet!
        
        Create a PulseFile. This creates an empty PulseFile with the specified backend.
        This _will_ overwrite pulsefiles with the same path. This does need an access
        layer, IMASPy does not provide one out of the box currently.
        ``` python
        from imas_entry._libs.imasdef import *
        input_user_or_path = <path to pulsefiles, for example your username>
        input_database = <database, for example 'iter' >
        imas_entry.create_env_backend(input_user_or_path, input_database, '3', MDSPLUS_BACKEND)
        ```
        
        Now that the pulse file exists, put some data in our Python structure:
        ``` python
        ids = imas_entry.equilibrium
        ids.ids_properties.homogeneous_time = 'special' #Whoops! This crashes, wrong type!
        ids.ids_properties.homogeneous_time = IDS_TIME_MODE_HETEROGENEOUS # This field needs to be filled for all valid IDSs
        ids.time = [0.1, 0.2, 0.3]
        ids.time += 2 # Let's offset this by 2
        ```
        
        No database interaction has happened yet. We need to explicitly send it to the
        MDSPLUS pulsefile:
        ``` python
        ids.put() # This removes the pulsefile, and rebuilds it with our in-memory structure!
        ```
        
        And now we can interact with the regular IMAS tools, for example to plot the
        structures with IMASViz.
        
        
        ### Prerequisites
        
        IMASPy is a standalone python package with optional dependencies. All needed
        python packages can be found in `requirements.txt`, and should all be publicly
        available. A simple `pip install` should take care of everything.
        
        #### Being IMAS DD compatible
        
        To check IMAS DD compatible, one needs the IDS definition XML file. This file
        can usually be found at `$IMAS_PREFIX/include/IDSDef.xml` on your IMAS-enabled
        system. Otherwise, they can be build from source from the
        [ITER IMAS Core Data Dictionary repository](https://git.iter.org/projects/IMAS/repos/data-dictionary/browse).
        
        #### Interacting with IMAS AL
        
        Interaction with the IMAS AL is provided by Cython and Python wrappers provided
        by the Python High Level Interface. As Cython code, it needs to be compiled on
        your local system. First make sure you can access the
        [ITER IMAS Access Layer repository](https://git.iter.org/projects/IMAS/repos/access-layer/browse)
        using SSH `ssh://git@git.iter.org/imas/access-layer.git`.
        A copy of this repository will be cloned into `src` during build.
        
        Get the prerequisites:
        ``` bash
        pip install numpy cython gitpython
        ```
        
        Install in verbose mode. After installing, you should have a `ual_x_x_x`
        directory in your root. If not, something went wrong. Be sure to browse
        the verbose log or open a ticket.
        ``` bash
        pip install --user -e .[all] -v
        ```
        
        ## Where does IMASPy live in IMAS ecosystem?
        IMASPy tries to fill a slightly different niche than existing tools. It aims
        to be an _alternative_ to Python HLI instead of a wrapper. It tries to be
        dynamic instead of pre-generated. Is hopes to be extendable instead of
        wrappable.
        
        A small, biased, and wildly incomplete of some common IMAS tools, and
        where they live with respect to IMASPy.
        ``` mermaid
        classDiagram
          MDSPLUS_DATABASE .. LL_AL : puts
          MDSPLUS_DATABASE .. LL_AL : gets
          MDSPLUS_DATABASE .. LL_HDC : puts
          MDSPLUS_DATABASE .. LL_HDC : gets
          IMAS DD <.. PythonHLI: build dep
          IMAS DD <-- IMASPy:  runtime dep
          LL_HDC <-- HDC_python_bindings : calls
          LL_AL <-- Cython_HLI : calls
          Python_helpers <-- IMASPy: calls
          HDC_python_bindings <.. IMASPy: Could call
        
          Cython_HLI <-- Python_helpers : calls
          Python_helpers <-- Python HLI: calls
        
          IMASDD <..  IMASviz_codegen: build dep
          IMASviz_codegen <..  IMASviz: build dep
        
          PythonHLI <-- OMAS: calls
          OMAS <-- OMFIT: calls
          OMFIT <-- IMASgo : calls
        
          PythonHLI <-- pyAL: calls
          PythonHLI <-- JINTRAC_WORKFLOWS : calls
          pyAL <-- HnCD_WORKFLOWS : calls
          PythonHLI <-- HnCD_WORKFLOWS : calls
          PythonHLI <-- IMASviz: calls
        ```
        
        ## Contributing
        
        IMASPy is open for contributions! Please open a
        [fork](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork)
        and create a
        [merge request](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#merging-upstream)
        or request developer access to one of the maintainers.
        
        ## License
        
        This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
        for details
        
        ## Acknowledgments
        
        Inspired and bootstrapped by existing tools, notably the IMAS Python HLI,
        IMAS Python workflows, and OMAS.
        
Platform: UNKNOWN
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >3.6
Description-Content-Type: text/markdown
Provides-Extra: backends_al
Provides-Extra: backends_xarray
Provides-Extra: examples
Provides-Extra: test
Provides-Extra: docs
Provides-Extra: all
