Python frontend

This section of the documentation deals with the Python frontend built for running and interacting with DREAM and its data. The code comprising the Python frontend is located under py/ and comprises three separate projects:

• py/DREAM/: the DREAM Python API which contains all scripts used to programmatically interact with DREAM input and output.

• py/cli/cli.py: simple script for interactively working with DREAM output.

• py/theater: The DREAM GUI interface which can be used to both configure and run DREAM simulations. Not yet implemented

Python API

The Python API, located under py/DREAM/, is the engine that powers all parts of the Python interface. It does not contain any runnable scripts, but rather holds several helper classes and functions which significantly simplify interaction with DREAM input and output. Aside from a few helper functions and classes located directly under the DREAM namespace, the interface is divided into two sections: DREAM.Settings and DREAM.Output. The former contains all code concerning DREAM input, while the latter deals with the output.

• ConvergenceScan
  • Input/output parameter by name
  • Input parameter custom function
  • Output parameter custom function
  • Scanning until convergence
  • Class documentation
• ConvergenceScanPlot
  • Class documentation
• DREAMOutput
  • Base classes
  • Equation system
  • Other quantities
  • Class documentation
• DREAMSettings
  • Basic usage
  • Chaining simulations
• runiface
  • Setting path to DREAM
  • Using runiface()
  • Parallel runiface()
• dreampyface
  • Compiling
  • Using the module
  • Implementation details
  • API Reference

Interactive CLI

The script py/cli/cli.py facilitates easier access to and interaction with DREAM output files. The script runs in interactive mode (i.e. python3 -i) and loads either the specified file or the file output.h5 in the current working directory as a DREAMOutput object. Additionally, all unknowns of the equation system are declared as global variables so that they can be directly access by name in the Python REPL. Example session:

$ /path/to/DREAM/py/cli/cli.py my-dream-output.h5
Loaded 8 unknowns (9.21 MiB)
DREAM Grid Object
   t: 11 elements from 0.0 to 0.010000000000000002
   r: 10 elements from 0.011 to 0.20899999999999996
   hottail   (p/xi)
      p:     1000 elements from 0.0005 to 0.9995
      xi:    10 elements from -0.9 to 0.9
   runaway   (DISABLED)

Unknowns:
   E_field, f_hot, n_cold, n_hot, n_i, n_re, n_tot, T_cold
>>> f_hot
(f_hot) Kinetic quantity of size NT x NR x NXI x NP = 11 x 10 x 10 x 1000
>>> np.sum(f_hot[:])
3.493714926993402e+26
>>> exit()

After running through the cli.py script which initializes the session, the Python interpreter switches to interactive mode allows the user to interact as usual. Everything you can normally do in the Python REPL can be done after running cli.py.

Most of the logic of the cli.py script is intentionaly kept in the function setup_interactive of the Python API. This allows users to easily put together their own versions of cli.py specialized to their particular needs. For example, the following variation of cli.py sets up an interactive environment and imports all numpy functions into the global namespace:

import matplotlib.pyplot as plt
from numpy import *

from DREAM import setup_interactive
from DREAM.DREAMOutput import DREAMOutput

do = DREAMOutput('output.h5')
setup_interactive(do, glob=globals())

# From this point on, the user will be able to interact
# with the DREAM output in the Python REPL...

All variables available in the interactive session are of the types defined in the Python API. More specifically, the unknowns of a DREAM Output equation system are loaded with the following types (at the time of writing):

Variable name	Data type
E_field	FluidQuantity
f_hot	HotElectronDistributionFunction
f_re	RunawayElectronDistributionFunction
I_p	ScalarQuantity
j_hot	FluidQuantity
j_ohm	FluidQuantity
j_tot	FluidQuantity
n_cold	FluidQuantity
n_hot	FluidQuantity
n_i	IonHandler
n_re	FluidQuantity
n_tot	FluidQuantity
psi_edge	ScalarQuantity
psi_p	FluidQuantity
T_cold	FluidQuantity
x_p	SPIShardPositions
Y_p	SPISardRadii

All other variables are loaded as UnknownQuantity if the type has not been explicitly specified in the dict SPECIAL_TREATMENT in EquationSystem.

Python/C++ interface

The regular Python API described above only operates on input and output files for DREAM, and never interacts with the C++ code. A set of bindings for Python, allowing the DREAM library to be called directly via Python, has however also been developed and is located under dreampyface. The primary goal of the Python bindings are to allow real-time monitoring of simulations using Python, such as for example continuously update plots of unknown quantities being evolved.

Read more about the Python bindings.

Warning

The DREAM and FVM libraries were originally designed for running single simulations at a time (i.e. relaunching the dreami program for each individual simulation to conduct). Because of this, not all memory is explicitly freed after the simulation finishes, which can lead to memory leaks when running several consecutive simulations using the Python bindings. We are aware of this problem and are working to avoid memory leaks as far as possible.

The DREAM Theater (GUI)

The DREAM Theater GUI has not yet been implemented