From bbbef682ec826c57f63da7b5d896aa2d4140772c Mon Sep 17 00:00:00 2001 From: VEZINET Didier Date: Tue, 3 Mar 2020 11:47:29 +0100 Subject: [PATCH 1/2] [new-doc] Added first version of tofu_from_bash.rst, with tofuplot --- doc/source/index.rst | 1 + doc/source/tofu_from_bash.rst | 173 ++++++++++++++++++++++++++++++++++ tofu/version.py | 2 +- 3 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 doc/source/tofu_from_bash.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index bbcc751dc..6c3086703 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -65,6 +65,7 @@ Contents A guide to contributing to tofu A list of all different device configurations available (ITER, WEST, JET, ...) Tutorials and examples + Using tofu from a bash terminal * How to create / handle a diagnostic geometry - Visit the basic_ tutorial for getting started: create, plot and save diff --git a/doc/source/tofu_from_bash.rst b/doc/source/tofu_from_bash.rst new file mode 100644 index 000000000..35989aecf --- /dev/null +++ b/doc/source/tofu_from_bash.rst @@ -0,0 +1,173 @@ +.. _command_line: + +Bash access to tofu +=================== + +tofu is a python library, and it through a python console that you'll get the most of it. +However, it also provides a few bash commands to be used straight form the terminal. +These commands provide a quick and simple access to a few very common features of tofu. +So far they include: + +- :ref:`tofuplot`: for interactive plotting of data from IMAS +- :ref:`tofucalc`: for computing and interactive plotting of synthetic data from IMAS +- :ref:`tofu-custom`: for setting-up your own tofu preferences + + +.. _tofuplot: + +tofuplot is available only if IMAS is also installed on your environment. +In that case, the sub-package imas2tofu will be operational. +This sub-package provides an interface between tofu and IMAS, and allows, +among other things, to use tofu to plot experimental data stored in IMAS in +interactive figure. + +This feature is typically used as follows: + +:: + + $ tofuplot -s 54178 -i ece + +The line above calls tofuplot with the following arguments: +- -s / --shot : the shot number of the imas data entry (here 54178) +- -i / --ids : the name of the ids we want to get data from (here ece) + +There are many other parameters that can be specified, like in particular: +- -tok / --tokamak: the name of the tokamak of the imas data entry +- -u / --user : the user of the imas data entry +- -t0 / --t0 : the name of the time event used as origin (can be a float) + +For help on the other parameters, type: + +:: + + $ tofuplot --help + + + +----- + +To install and use `tofu` on Linux, we recommend to proceed in two steps: install the +Python package manager conda and then install tofu. +We recommend ``Miniconda`` (light version of the Anaconda Python distribution for data science, +but you can also work with ``pip`` or another Python package manager of +your choice). + +- `Get the latest Miniconda version and install + it. `__ +- Install tofu + +:: + + $ conda install -c tofuproject tofu + +- Check that tofu works by printing its version number: + +:: + + $ python -c "import tofu; print(tofu.__version__)" + +Now you can `follow a tutorial. `__ + +.. _installing-tofu-on-mac: + +Mac OS X +-------- + +See :ref:`installing-as-a-developer`. + +Additional *caveat*: if you are using a version of `gcc < 8` be sure to +turn off all parallelizations since there is a `known bug with cython +`__. + +.. _installing-tofu-on-windows: + +Windows +------- + +See :ref:`installing-as-a-developer`. + +Additional *caveat*: you may need to open an ``Anaconda prompt`` (usually found by pressing +the Windows key) to run the commands described in the linked section. + + +.. _iter-users: + +Using tofu on a ITER cluster +---------------------------- + +If you have an **ITER** account, you can use **tofu** directly from ITER +Computing Cluster. No need to install tofu ! + +- Ask for access to ITER servers, if you don't have them already. +- For information about the cluster, see `this + link. `__ +- Open a new terminal and connect to server (see link above) +- Create a new file in your ``$HOME`` directory, you can name it + ``load_tofu_modules.sh`` +- Open it and add the following lines: + +:: + + module refresh + source /etc/profile.d/modules.sh # make sure you have the module environment + module purge # unload any previously loaded modules + module load IMAS/3.24.0-4.1.5 # for IMAS data base + module load IPython/6.3.1-intel-2018a-Python-3.6.4 # for iPython + module load PySide2/5.12.0-intel-2018a-Python-3.6.4 + module load ToFu/1.4.0-intel-2018a-Python-3.6.4 # Load tofu :) + +- Convert it to an executable, from the terminal: + ``chmod +x ~/load_tofu_modules.sh`` +- Execute it: ``./load_tofu_modules.sh`` +- If you are going to use *tofu* often, you might want to add the + execution of the script to your ``.bash_profile`` (or ``.bashrc`` + file): + +:: + + echo './load_tofu_modules.sh' >> .bash_profile + +You are all set, open a Python/IPython console and try importing tofu. + +:: + + $ python + In [1]: import tofu as tf + +You can now `follow a tutorial. `__ + + +.. _installing-as-a-developer: + +Installing tofu as a developer +------------------------------ + +To install tofu as a developer, we recommend using the conda ecosystem (Miniconda in particular): + +- `Get the latest Miniconda version and install + it. `__ + +- create a dedicated (Python 3) environment for tofu development and activate it + +:: + + $ conda create -n tofu3 python=3.6 scipy numpy cython git + $ conda activate tofu3 + +- Move to where you would like to install your local copy of ToFu ``$ cd some_path`` +- ``$ git clone https://github.com/ToFuProject/tofu.git`` (make sure you + remember the path where you are installing, if you want to install it + into your home repository, just make sure to ``$ cd ~`` before the + ``git clone...``) +- Move to the "cloned" tofu directory that has been created by the git clone command: + ``cd ~/tofu`` +- Switch to the ``git`` branch you will be working on. If you are just + starting you probably want to start from the latest develop branch: + ``git checkout devel``. If you are not familiar with **git** take a + look at `this tutorial + (long) `__ or `this short + one `__ +- Run ``pip install -e .[dev]``. This will install dependencies, compile the + tofu cython extensions and install it into your conda environment while you can still + modify the source files in the current repository.` +- Make sure tofu tests are running by typing ``nosetests`` diff --git a/tofu/version.py b/tofu/version.py index 1775fee64..db64db1fe 100644 --- a/tofu/version.py +++ b/tofu/version.py @@ -1,2 +1,2 @@ # Do not edit, pipeline versioning governed by git tags! -__version__ = '1.4.2b13-70-gf5b8d06e' +__version__ = '1.4.2b13-76-ge312f125' From f5484b84a8c57b86526f0aa4df53e70ce9899c19 Mon Sep 17 00:00:00 2001 From: VEZINET Didier Date: Tue, 3 Mar 2020 12:52:31 +0100 Subject: [PATCH 2/2] [new-doc] added doc/source/tofu_from_bash.rst --- doc/source/tofu.data.rst | 75 +++---- doc/source/tofu.dumpro.rst | 67 +++--- doc/source/tofu.dust.rst | 37 ++-- doc/source/tofu.geom.rst | 143 ++++++------- doc/source/tofu.rst | 67 +++--- doc/source/tofu.scripts.rst | 34 +++ doc/source/tofu.tests.rst | 17 ++ doc/source/tofu.tests.tests00_root.rst | 18 ++ doc/source/tofu.tests.tests01_geom.rst | 41 ++++ ...u.tests.tests01_geom.tests03_core_data.rst | 138 ++++++++++++ doc/source/tofu.tests.tests02_data.rst | 18 ++ doc/source/tofu.tests.tests09_tutorials.rst | 42 ++++ doc/source/tofu_from_bash.rst | 202 +++++++++--------- tofu/version.py | 2 +- 14 files changed, 608 insertions(+), 293 deletions(-) create mode 100644 doc/source/tofu.scripts.rst create mode 100644 doc/source/tofu.tests.rst create mode 100644 doc/source/tofu.tests.tests00_root.rst create mode 100644 doc/source/tofu.tests.tests01_geom.rst create mode 100644 doc/source/tofu.tests.tests01_geom.tests03_core_data.rst create mode 100644 doc/source/tofu.tests.tests02_data.rst create mode 100644 doc/source/tofu.tests.tests09_tutorials.rst diff --git a/doc/source/tofu.data.rst b/doc/source/tofu.data.rst index 952cfb5df..a22984fe1 100644 --- a/doc/source/tofu.data.rst +++ b/doc/source/tofu.data.rst @@ -2,66 +2,57 @@ tofu.data package ================= .. automodule:: tofu.data - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: Submodules ---------- -tofu.data.\_comp module ------------------------ +tofu.data._comp module +---------------------- .. automodule:: tofu.data._comp - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.data.\_core module ------------------------ +tofu.data._core module +---------------------- .. automodule:: tofu.data._core - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.data.\_core\_new module ----------------------------- +tofu.data._core_new module +-------------------------- .. automodule:: tofu.data._core_new - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.data.\_def module ----------------------- +tofu.data._def module +--------------------- .. automodule:: tofu.data._def - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.data.\_physics module --------------------------- - -.. automodule:: tofu.data._physics - :members: - :undoc-members: - :show-inheritance: - -tofu.data.\_plot module ------------------------ +tofu.data._plot module +---------------------- .. automodule:: tofu.data._plot - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.data.\_spectrafit2d module -------------------------------- +tofu.data._spectrafit2d module +------------------------------ .. automodule:: tofu.data._spectrafit2d - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.dumpro.rst b/doc/source/tofu.dumpro.rst index 18f2bfe1f..0c10ac5c0 100644 --- a/doc/source/tofu.dumpro.rst +++ b/doc/source/tofu.dumpro.rst @@ -2,58 +2,57 @@ tofu.dumpro package =================== .. automodule:: tofu.dumpro - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: Submodules ---------- -tofu.dumpro.\_comp module -------------------------- +tofu.dumpro._comp module +------------------------ .. automodule:: tofu.dumpro._comp - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dumpro.\_comp\_clusters module ------------------------------------ +tofu.dumpro._comp_clusters module +--------------------------------- .. automodule:: tofu.dumpro._comp_clusters - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dumpro.\_core module -------------------------- +tofu.dumpro._core module +------------------------ .. automodule:: tofu.dumpro._core - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dumpro.\_def module ------------------------- +tofu.dumpro._def module +----------------------- .. automodule:: tofu.dumpro._def - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dumpro.\_draft module --------------------------- +tofu.dumpro._draft module +------------------------- .. automodule:: tofu.dumpro._draft - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dumpro.\_plot module -------------------------- +tofu.dumpro._plot module +------------------------ .. automodule:: tofu.dumpro._plot - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.dust.rst b/doc/source/tofu.dust.rst index 5fdc6c022..7cddce06d 100644 --- a/doc/source/tofu.dust.rst +++ b/doc/source/tofu.dust.rst @@ -2,34 +2,33 @@ tofu.dust package ================= .. automodule:: tofu.dust - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: Submodules ---------- -tofu.dust.\_comp module ------------------------ +tofu.dust._comp module +---------------------- .. automodule:: tofu.dust._comp - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dust.\_core module ------------------------ +tofu.dust._core module +---------------------- .. automodule:: tofu.dust._core - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.dust.\_plot module ------------------------ +tofu.dust._plot module +---------------------- .. automodule:: tofu.dust._plot - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.geom.rst b/doc/source/tofu.geom.rst index 713d9d717..11dc74960 100644 --- a/doc/source/tofu.geom.rst +++ b/doc/source/tofu.geom.rst @@ -2,122 +2,121 @@ tofu.geom package ================= .. automodule:: tofu.geom - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: Submodules ---------- -tofu.geom.\_GG module ---------------------- +tofu.geom._GG module +-------------------- .. automodule:: tofu.geom._GG - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_basic\_geom\_tools module -------------------------------------- +tofu.geom._basic_geom_tools module +---------------------------------- .. automodule:: tofu.geom._basic_geom_tools - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_comp module ------------------------ +tofu.geom._comp module +---------------------- .. automodule:: tofu.geom._comp - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_comp\_optics module -------------------------------- +tofu.geom._comp_optics module +----------------------------- .. automodule:: tofu.geom._comp_optics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_core module ------------------------ +tofu.geom._core module +---------------------- .. automodule:: tofu.geom._core - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_core\_optics module -------------------------------- +tofu.geom._core_optics module +----------------------------- .. automodule:: tofu.geom._core_optics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_def module ----------------------- +tofu.geom._def module +--------------------- .. automodule:: tofu.geom._def - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_distance\_tools module ----------------------------------- +tofu.geom._distance_tools module +-------------------------------- .. automodule:: tofu.geom._distance_tools - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_plot module ------------------------ +tofu.geom._plot module +---------------------- .. automodule:: tofu.geom._plot - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_plot\_optics module -------------------------------- +tofu.geom._plot_optics module +----------------------------- .. automodule:: tofu.geom._plot_optics - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_raytracing\_tools module ------------------------------------- +tofu.geom._raytracing_tools module +---------------------------------- .. automodule:: tofu.geom._raytracing_tools - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_sampling\_tools module ----------------------------------- +tofu.geom._sampling_tools module +-------------------------------- .. automodule:: tofu.geom._sampling_tools - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: -tofu.geom.\_vignetting\_tools module ------------------------------------- +tofu.geom._vignetting_tools module +---------------------------------- .. automodule:: tofu.geom._vignetting_tools - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: tofu.geom.utils module ---------------------- .. automodule:: tofu.geom.utils - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.rst b/doc/source/tofu.rst index cf238008d..384b0da2f 100644 --- a/doc/source/tofu.rst +++ b/doc/source/tofu.rst @@ -2,60 +2,77 @@ tofu package ============ .. automodule:: tofu - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: Subpackages ----------- .. toctree:: - tofu.data - tofu.dumpro - tofu.dust - tofu.geom + tofu.data + tofu.dumpro + tofu.dust + tofu.geom + tofu.scripts + tofu.tests Submodules ---------- -tofu.\_plot module ------------------- +tofu._physics module +-------------------- + +.. automodule:: tofu._physics + :members: + :undoc-members: + :show-inheritance: + +tofu._plot module +----------------- .. automodule:: tofu._plot - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: tofu.defaults module -------------------- .. automodule:: tofu.defaults - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: tofu.pathfile module -------------------- .. automodule:: tofu.pathfile - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + +tofu.plot_create_geometry module +-------------------------------- + +.. automodule:: tofu.plot_create_geometry + :members: + :undoc-members: + :show-inheritance: tofu.utils module ----------------- .. automodule:: tofu.utils - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: tofu.version module ------------------- .. automodule:: tofu.version - :members: - :undoc-members: - :show-inheritance: - + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.scripts.rst b/doc/source/tofu.scripts.rst new file mode 100644 index 000000000..20b342883 --- /dev/null +++ b/doc/source/tofu.scripts.rst @@ -0,0 +1,34 @@ +tofu.scripts package +==================== + +.. automodule:: tofu.scripts + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +tofu.scripts.tofucalc module +---------------------------- + +.. automodule:: tofu.scripts.tofucalc + :members: + :undoc-members: + :show-inheritance: + +tofu.scripts.tofucustom module +------------------------------ + +.. automodule:: tofu.scripts.tofucustom + :members: + :undoc-members: + :show-inheritance: + +tofu.scripts.tofuplot module +---------------------------- + +.. automodule:: tofu.scripts.tofuplot + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.tests.rst b/doc/source/tofu.tests.rst new file mode 100644 index 000000000..5317cd636 --- /dev/null +++ b/doc/source/tofu.tests.rst @@ -0,0 +1,17 @@ +tofu.tests package +================== + +.. automodule:: tofu.tests + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + tofu.tests.tests00_root + tofu.tests.tests01_geom + tofu.tests.tests02_data + tofu.tests.tests09_tutorials diff --git a/doc/source/tofu.tests.tests00_root.rst b/doc/source/tofu.tests.tests00_root.rst new file mode 100644 index 000000000..216d418b1 --- /dev/null +++ b/doc/source/tofu.tests.tests00_root.rst @@ -0,0 +1,18 @@ +tofu.tests.tests00_root package +=============================== + +.. automodule:: tofu.tests.tests00_root + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +tofu.tests.tests00_root.tests03_plot module +------------------------------------------- + +.. automodule:: tofu.tests.tests00_root.tests03_plot + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.tests.tests01_geom.rst b/doc/source/tofu.tests.tests01_geom.rst new file mode 100644 index 000000000..04d5ec0f5 --- /dev/null +++ b/doc/source/tofu.tests.tests01_geom.rst @@ -0,0 +1,41 @@ +tofu.tests.tests01_geom package +=============================== + +.. automodule:: tofu.tests.tests01_geom + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + tofu.tests.tests01_geom.tests03_core_data + +Submodules +---------- + +tofu.tests.tests01_geom.tests01_GG module +----------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests01_GG + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests02_compute module +---------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests02_compute + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core module +------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.tests.tests01_geom.tests03_core_data.rst b/doc/source/tofu.tests.tests01_geom.tests03_core_data.rst new file mode 100644 index 000000000..90cba47be --- /dev/null +++ b/doc/source/tofu.tests.tests01_geom.tests03_core_data.rst @@ -0,0 +1,138 @@ +tofu.tests.tests01_geom.tests03_core_data package +================================================= + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +tofu.tests.tests01_geom.tests03_core_data.WEST_CoilPF_Notes module +------------------------------------------------------------------ + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_CoilPF_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_Baffle_Notes module +---------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_Baffle_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_BumperInner_Notes module +--------------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_BumperInner_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_BumperOuter_Notes module +--------------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_BumperOuter_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivLowGC_Notes module +------------------------------------------------------------------------ + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivLowGC_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivLowITER_Notes module +-------------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivLowITER_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivUp_Notes module +--------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_DivUp_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC1_Notes module +------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC1_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC2_Notes module +------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC2_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC3_Notes module +------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_IC3_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_LH1_Notes module +------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_LH1_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_LH2_Notes module +------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_LH2_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_Ripple_Notes module +---------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PFC_Ripple_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_PlasmaDomain_Standard_Notes module +--------------------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_PlasmaDomain_Standard_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_Ves_VesIn_Notes module +--------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_Ves_VesIn_Notes + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests01_geom.tests03_core_data.WEST_Ves_VesOut_Notes module +---------------------------------------------------------------------- + +.. automodule:: tofu.tests.tests01_geom.tests03_core_data.WEST_Ves_VesOut_Notes + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.tests.tests02_data.rst b/doc/source/tofu.tests.tests02_data.rst new file mode 100644 index 000000000..64e67a145 --- /dev/null +++ b/doc/source/tofu.tests.tests02_data.rst @@ -0,0 +1,18 @@ +tofu.tests.tests02_data package +=============================== + +.. automodule:: tofu.tests.tests02_data + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +tofu.tests.tests02_data.tests03_core module +------------------------------------------- + +.. automodule:: tofu.tests.tests02_data.tests03_core + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu.tests.tests09_tutorials.rst b/doc/source/tofu.tests.tests09_tutorials.rst new file mode 100644 index 000000000..d8c3de2d0 --- /dev/null +++ b/doc/source/tofu.tests.tests09_tutorials.rst @@ -0,0 +1,42 @@ +tofu.tests.tests09_tutorials package +==================================== + +.. automodule:: tofu.tests.tests09_tutorials + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +tofu.tests.tests09_tutorials.tests01_runall module +-------------------------------------------------- + +.. automodule:: tofu.tests.tests09_tutorials.tests01_runall + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests09_tutorials.tuto_plot_basic module +--------------------------------------------------- + +.. automodule:: tofu.tests.tests09_tutorials.tuto_plot_basic + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests09_tutorials.tuto_plot_create_geometry module +------------------------------------------------------------- + +.. automodule:: tofu.tests.tests09_tutorials.tuto_plot_create_geometry + :members: + :undoc-members: + :show-inheritance: + +tofu.tests.tests09_tutorials.tuto_plot_custom_emissivity module +--------------------------------------------------------------- + +.. automodule:: tofu.tests.tests09_tutorials.tuto_plot_custom_emissivity + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/source/tofu_from_bash.rst b/doc/source/tofu_from_bash.rst index 35989aecf..46adda50e 100644 --- a/doc/source/tofu_from_bash.rst +++ b/doc/source/tofu_from_bash.rst @@ -15,11 +15,14 @@ So far they include: .. _tofuplot: +tofuplot +-------- + tofuplot is available only if IMAS is also installed on your environment. In that case, the sub-package imas2tofu will be operational. This sub-package provides an interface between tofu and IMAS, and allows, among other things, to use tofu to plot experimental data stored in IMAS in -interactive figure. +interactive figures. This feature is typically used as follows: @@ -31,143 +34,142 @@ The line above calls tofuplot with the following arguments: - -s / --shot : the shot number of the imas data entry (here 54178) - -i / --ids : the name of the ids we want to get data from (here ece) -There are many other parameters that can be specified, like in particular: -- -tok / --tokamak: the name of the tokamak of the imas data entry -- -u / --user : the user of the imas data entry -- -t0 / --t0 : the name of the time event used as origin (can be a float) +The ids names that can be used are diagnostic ids, they include: +- soft_x_rays +- bolometer +- interferometer +- polarimeter +- reflectometer_profile +- barometry +- spectrometer_visible +- bremsstrahlung_visible -For help on the other parameters, type: +Note that you can combine the plots from several ids in the same figure by +simply adding more ids (they will have common time axis): :: - $ tofuplot --help + $ tofuplot -s 54178 -i ece soft_x_rays interferometer +In all cases, what tofuplot does is simply: +- read the tokamak geometry from ids wall +- read the diagnostic geometry from the provided ids +- compute the Lines of Sight (LOS) +- read the diagnostic experimental data from the provided ids +- display the data (time traces per LOS) and the geometry (tokamak + LOS) in + an interactive figure ------ +There are many other parameters that can be specified, like in particular: +- -tok / --tokamak: the name of the tokamak of the imas data entry +- -u / --user : the user of the imas data entry +- -t0 / --t0 : the name of the time event used as origin (can be a float) -To install and use `tofu` on Linux, we recommend to proceed in two steps: install the -Python package manager conda and then install tofu. -We recommend ``Miniconda`` (light version of the Anaconda Python distribution for data science, -but you can also work with ``pip`` or another Python package manager of -your choice). +When a parameter is not specified, a default value is used. -- `Get the latest Miniconda version and install - it. `__ -- Install tofu +For help on the other parameters, type: :: - $ conda install -c tofuproject tofu - -- Check that tofu works by printing its version number: + $ tofuplot --help -:: +Here is an example of the interactive figure - $ python -c "import tofu; print(tofu.__version__)" -Now you can `follow a tutorial. `__ -.. _installing-tofu-on-mac: +.. _tofucalc: -Mac OS X +tofucalc -------- -See :ref:`installing-as-a-developer`. +tofuplot simply reads and plot data. -Additional *caveat*: if you are using a version of `gcc < 8` be sure to -turn off all parallelizations since there is a `known bug with cython -`__. +By comparison, tofucalc also reads the diagnostics geometry, +but more importantly, it reads plasma profiles (1d radial profiles or 2d maps) +of the quantity of interest for the chosen diagnostic +(i.e.: electron density for interferometer, total radiated power for +bolometer...) and calculates the synthetic data of the +diagnostic (it performs the Line Of Sight integrationi of the quantity). +Finally, it displays the result in the same interactive figure as tofuplot. -.. _installing-tofu-on-windows: +Once you have understood the parameters of tofuplot, tofucalc is intuitive +as it requires the same input: -Windows -------- +:: -See :ref:`installing-as-a-developer`. + $ tofucalc -s 54178 -i interferometer + +Note however, that tofucalc is available for a limited number of diagnostics. +Indeed, it requires pre-tabulating the quantity of interest for each ids and +implementing proper 2D interpolation methods for each type of profile. +So far, it is available for: +- interefreometer +- polarimeter +- bolometer +- bremsstrhalung_visible + +Other diagnostics / ids will be added to this list as tofu is developped and +tested on WEST. + +Also note that there is a default profile tabulated for each diagostics. +For example interferometer used the 1d electron density profile stored in ids +core_profiles. +But one could of course object that electron density can be stored as a 2D map +in another ids, produced, for example by a plasma edge code. +Computing synthetic data from an alternative source than the tabulated default +o ne is possible, but through the python console only as it requires a more +advanced use of the features offered by tofu. + +For some specific users, an alternative way of providing the profiles has been +implemented: it is possible to pass the ids not by its identification +parameters (shot, user, tokamak, ids name...), but via an input file saved with +matlab (.mat). +The input file shall contain an exact representation of the ids. +Likewise, the result can be saved into a .mat output file. +This feature is only available for ids bremsstrahlung_visible so far and it +only the 1d radiation profile that is passed throught the input file. +The equilibrium (for interpolation) and diagnostic geometry are still read from +regular IMAS ids. -Additional *caveat*: you may need to open an ``Anaconda prompt`` (usually found by pressing -the Windows key) to run the commands described in the linked section. +:: + $ tofucalc -s 54178 -i interferometer -.. _iter-users: -Using tofu on a ITER cluster ----------------------------- -If you have an **ITER** account, you can use **tofu** directly from ITER -Computing Cluster. No need to install tofu ! -- Ask for access to ITER servers, if you don't have them already. -- For information about the cluster, see `this - link. `__ -- Open a new terminal and connect to server (see link above) -- Create a new file in your ``$HOME`` directory, you can name it - ``load_tofu_modules.sh`` -- Open it and add the following lines: +.. _tofu-custom: -:: +tofu-custom +----------- - module refresh - source /etc/profile.d/modules.sh # make sure you have the module environment - module purge # unload any previously loaded modules - module load IMAS/3.24.0-4.1.5 # for IMAS data base - module load IPython/6.3.1-intel-2018a-Python-3.6.4 # for iPython - module load PySide2/5.12.0-intel-2018a-Python-3.6.4 - module load ToFu/1.4.0-intel-2018a-Python-3.6.4 # Load tofu :) - -- Convert it to an executable, from the terminal: - ``chmod +x ~/load_tofu_modules.sh`` -- Execute it: ``./load_tofu_modules.sh`` -- If you are going to use *tofu* often, you might want to add the - execution of the script to your ``.bash_profile`` (or ``.bashrc`` - file): +tofu used a lot of default parameters, such that providing no parameter at all +is ok when using most method / functions. +However, you may want to customize some of these default parameters to better +suit your usage or liking. -:: +If tofu is installed on a shared cluster, you can't access tofu's default +parametersas modifying them would also affect everybody else's usage. - echo './load_tofu_modules.sh' >> .bash_profile - -You are all set, open a Python/IPython console and try importing tofu. +In order to allow for user-specific customization, run: :: - $ python - In [1]: import tofu as tf - -You can now `follow a tutorial. `__ - + $ tofu-custom -.. _installing-as-a-developer: -Installing tofu as a developer ------------------------------- +This will create a .tofu/ directory in your home (~/), in which tofu will copy +default parameters and data that you are free to edit. +This local copy is thus user-specific and will always have precedence when +importing tofu. -To install tofu as a developer, we recommend using the conda ecosystem (Miniconda in particular): +Not all parameters can be customized, and this effort is on-going, but to, +as of tofu 1.4.3, you can edit: +- the imas shortcuts in _imas2tofu-def.py +- the default parameters of tofuplot and tofcalc in _scripts_def.py -- `Get the latest Miniconda version and install - it. `__ - -- create a dedicated (Python 3) environment for tofu development and activate it - -:: +Other parameters will be available for customization in future versions. - $ conda create -n tofu3 python=3.6 scipy numpy cython git - $ conda activate tofu3 - -- Move to where you would like to install your local copy of ToFu ``$ cd some_path`` -- ``$ git clone https://github.com/ToFuProject/tofu.git`` (make sure you - remember the path where you are installing, if you want to install it - into your home repository, just make sure to ``$ cd ~`` before the - ``git clone...``) -- Move to the "cloned" tofu directory that has been created by the git clone command: - ``cd ~/tofu`` -- Switch to the ``git`` branch you will be working on. If you are just - starting you probably want to start from the latest develop branch: - ``git checkout devel``. If you are not familiar with **git** take a - look at `this tutorial - (long) `__ or `this short - one `__ -- Run ``pip install -e .[dev]``. This will install dependencies, compile the - tofu cython extensions and install it into your conda environment while you can still - modify the source files in the current repository.` -- Make sure tofu tests are running by typing ``nosetests`` +This hidden directory also holds a openadas2tofu/ sub-directory where all data +downloaded by tofu from `openadas `__ +(a free online atomic database) is stored. diff --git a/tofu/version.py b/tofu/version.py index 80e637748..5411364c7 100644 --- a/tofu/version.py +++ b/tofu/version.py @@ -1,2 +1,2 @@ # Do not edit, pipeline versioning governed by git tags! -__version__ = '1.4.2b13-77-gbbbef682' +__version__ = '1.4.2b4-69-gdddc7bfb'