Welcome to xemc3’s documentation!

xemc3 provides an interface for collecting the output data from a EMC3 simulation into an xarray dataset, as well as accessor methods for common EMC3 analysis and plotting tasks.

Currently only in alpha (until 1.0 released) so please report any bugs, and feel free to raise issues asking questions or making suggestions.

Getting started

Installing

To get the full install including plotting run:

pip install --user 'xemc3[full]'

If you want a minimal install without plotting capabilities you can run:

pip install --user xemc3

Note that without matplotlib plotting will not be available.

Basic tasks

Checking convergence

If you have run a simulations, typically the first thing you want to do, is check the *_INFO files to check whether the simulation is converged.

This can be done by reading in the info files, and plotting the traces, to have a look at the variation:

import xemc3
import matplotlib.pyplot as plt
ds = xemc3.load.file("path_to_simu/ENERGY_INFO")
for key in ds:
    ds[key].plot()
plt.show()

See an example notebook for more info on reading these files.

Reading the output

xemc3 assumes that all files are called the way that also EMC3 is expecting them to be named. If you use different names, ensure that the files are linked to the EMC3 names, before loading the files with xemc3.

Once the simulation is sufficiently converged, further analysis can start. For this xemc3 allows to read in all the files, and store the data as a netcdf file. This has the advantage that successive reads are very fast, and is especially convenient if the data is stored in the netcdf file after running the simulation. There is a command line version, that can be conveniently called from shell, xemc3-to-netcdf that is roughly equivalent to the following python snippet:

import xemc3
ds = xemc3.load.all(path)
ds.to_netcdf(path + ".nc")

Besides faster loads, the netcdf also makes it easier to share the data for analysis, as all data is stored in a single file. This also allows to unlink the EMC3 names, or share the data with users that have a different naming convention for their files. The netcdf files can then be read again via

import xarray as xr
ds = xr.open_dataset(path + ".nc")

Post processing

xarray provides a wide variety of functionality for post processing. Good documentation and tutorials are available.

Plotting

xarray handles plotting already, but xemc3 extends this with some more specific routines, for example to plot an \(R\times z\) slice. The functionally is documented here and can be accessed via the emc3 accessor of a dataset, for example the xemc3.EMC3DatasetAccessor.plot_rz can be used by calling ds.emc3.plot_rz(...) with ds an xr.Dataset. Plotting in simulation coordinates can be done using xr.DataArray.plot as e.g. ds["Te"].isel(r=-3).plot() to plot the third outermost slice of the electron temperature.

Exercises

To get an overview what is possible with xemc3, you can try the exercises.

You can find them in the docs/exercises/ folder or try them online.

Examples

Evaluate at

Some examples of the evaluate_at functionality

[1]:

import xarray as xr
import numpy as np
import xemc3
import matplotlib.pyplot as plt

# Matplotlib setup
import setup_plt

[2]:

# Use local helper function to get some data
from get_data import load_example_data

ds = load_example_data()
# If you want to use your own data use something like
# ds = xemc3.load.all("path/to/mydata/")
# or if you have converted it already to a netcdf file
# ds = xr.open_dataset("path/to/mydata.nc")

Evaluate along a line of sight

[3]:

nx = 1000
mapped = ds.emc3.evaluate_at_xyz(
    np.linspace(4.8, 6.0, nx),
    np.linspace(-0.1, 0.1, nx),
    np.linspace(-0.5, 0.5, nx),
    "ne",
    periodicity=5,
    updownsym=True,
    delta_phi=np.pi / 1800,
)
# Add a coordinate
mapped.coords["dim_0"] = np.linspace(4.8, 6.0, nx)
mapped.dim_0.attrs = dict(units="m", long_name="x")

[4]:

plt.figure()
mapped["ne"].plot()

[4]:

[<matplotlib.lines.Line2D at 0x7fcd7b959970>]

Evaluate along a 2D array

Plotting an \(R\times z\) plane can be done with ds.emc3.plot_rz(key, phi) this allows to plot abitrary cuts of the domain.

[5]:

# Evaluate an abitrary 2D slice
x = xr.DataArray(np.linspace(0, 7, 100), name="x", dims="x", attrs=dict(units="m"))
y = xr.DataArray(np.linspace(0, 7, 100), name="y", dims="y", attrs=dict(units="m"))
z = 0
# Add coordinates:
x.coords["x"] = x
y.coords["y"] = y


mapped = ds.emc3.evaluate_at_xyz(
    x, y, z, ["ne", "Te"], periodicity=5, updownsym=True, delta_phi=np.pi / 180
)

[6]:

# Plot the pressure
plt.figure()
(mapped.ne * mapped.Te).plot(x="x", y="y")

[6]:

<matplotlib.collections.QuadMesh at 0x7fcd7976f520>

Precalculate the mapping

Rather then directly evaluating a quantity, we can also calculate the mapping first. This is usefull if the same mapping is needed for different simulations, as long as they use the identical grid.

[7]:

# Evaluate an abitrary 2D slice
x = xr.DataArray(np.linspace(0, 7, 100), name="x", dims="x", attrs=dict(units="m"))
y = xr.DataArray(np.linspace(0, 7, 100), name="y", dims="y", attrs=dict(units="m"))
z = 0
# Add coordinates:
x.coords["x"] = x
y.coords["y"] = y

# We don't pass in the key we want to evaluate
# In this case we get a dataset with indices
mapped = ds.emc3.evaluate_at_xyz(
    x, y, z, key=None, periodicity=5, updownsym=True, delta_phi=np.pi / 180
)

[8]:

# This time we calculate the pressure
ds["Pe"] = ds.Te * ds.ne
# And then we evaluate with the pre-evaluated indices the pressure in the plane
plt.figure()
ds["Pe"].isel(**mapped).plot(x="x", y="y")

[8]:

<matplotlib.collections.QuadMesh at 0x7fcd7962a310>

Evaluate along a field line

xemc3 doesn’t support field-line tracing

We can however use the webservices, if we are on the IPP network

Warning

Please note that if you don’t use the same magnetic configuration in the fieldlinetracer and the simulations, you might get slightly wrong results or completely wrong results.

Especially, conclusion drawn might be completely wrong!

Always double check the magnetic configurations!

[9]:

try:
    from dave_utils import jafw
except ImportError:
    print("Importing failed. Consider installing dave_utils with:")
    print("pip install --user git+https://gitlab.mpcdf.mpg.de/dave/dave_utils.git")
    jafw = None
    raise

# This will fail outside of the IPP network
flt = jafw.getSrv()

config = jafw.setCurrents([-1.74e6] * 5 + [0] * 5)

pos = flt.types.Points3D()
pos.x1 = 5.7
pos.x2 = 0
pos.x3 = 0

lineTask = flt.types.LineTracing()
lineTask.numSteps = 3000

task = flt.types.Task()
task.step = 0.01
task.lines = lineTask

res = flt.service.trace(pos, config, task, None, None)

i = 0
dat = np.array(
    [
        res.lines[i].vertices.x1,
        res.lines[i].vertices.x2,
        res.lines[i].vertices.x3,
    ]
)
mapped = ds.emc3.evaluate_at_xyz(
    dat[0],
    dat[1],
    dat[2],
    "ne",
    periodicity=5,
    updownsym=True,
    delta_phi=np.pi / 180,
)

Importing failed. Consider installing dave_utils with:
pip install --user git+https://gitlab.mpcdf.mpg.de/dave/dave_utils.git

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[9], line 2
      1 try:
----> 2     from dave_utils import jafw
      3 except ImportError:
      4     print("Importing failed. Consider installing dave_utils with:")

ModuleNotFoundError: No module named 'dave_utils'

[10]:

if jafw is not None:
    mapped["ne"].plot(figsize=(16, 6))
else:
    print("Fieldlinetracer not available ...")

Fieldlinetracer not available ...

Heatflux post processing

Documenation of the EMC3-EIRENE is part of the EMC3-EIRENE documentation

map particle and density deposition ENERGY_DEPO and PARTICLE_DEPO to the target structures
Target heatflux contains contribution from potential energy
Neutrals are not included
plasma radiation not included

[ ]:

# Ensure the example data is present
from get_data import load_example_data

_ = load_example_data()

[ ]:

# Input file
! cat ../../example-data/emc3_example/fort.3

[ ]:

# Input file
! cat ../../example-data/emc3_example/fort.79

Run with e.g.

cd /raven/u/mp004/runs/casegroup/case_docs/
srun emc3_eirene

[4]:

# xemc3 can be used for plotting:
! xemc3-divertor ../../example-data/emc3_example/ -gls -t 'Example data'

Analysing the data

[ ]:

import xemc3

[ ]:

plates = xemc3.load.plates("../../example-data/emc3_example/")

[ ]:

plates

The data contains padding such that they can be combined into a numpy-data-block

[ ]:

plates["f_E"].isel(plate_ind=13).plot()

Using the ds.emc3[] the padding can be removed, if it not not needed for the current data, i.e. if only a single plate is included:

[ ]:

nosym = list(plates.emc3.iter_plates())
nosym[13].emc3["f_E"].plot()
nosym[13]

It is possible to get all plates, rather then just the simulated half-module using the ds.emc3.iter_plates function:

[ ]:

sym = list(plates.emc3.iter_plates(symmetry=True, segments=5))
len(sym)

Loading the raw data is slow

As several text files have to be read and parsed, this is rather time consuming.

See Loading of data for a more convienent way to work with EMC3 data.

[1]:

import xemc3

[2]:

%%time

ds = xemc3.load.all("../../example-data/emc3_example/")

CPU times: user 1min 1s, sys: 301 ms, total: 1min 1s
Wall time: 1min 2s

Welcome to xemc3’s documentation!

Getting started

Installing

Basic tasks

Checking convergence

Reading the output

Post processing

Plotting

Exercises

Examples

Evaluate at

Evaluate along a line of sight

Evaluate along a 2D array

Precalculate the mapping

Evaluate along a field line

Warning

Heatflux post processing

Analysing the data

Analysing traces

Reading some files

Reading all INFO files

Checking how much data

Introduction to xemc3

Quick introduction to xarray

data.values

data.dims

data.coords

data.attrs

More on xarray:

EMC3 data

dataset (ds) explanation

ds.coords[‘R_bounds’]

ds.coords[‘z_bounds’]

ds.coords[‘phi_bounds’]

Toroidal slice

ds.coords[‘phi_bounds’]

ds.emc3.plot_rz(key, phi = \(\phi\))

Simplifying of grid structure

Use of NaN values in xEMC3

Grid

Grid with boundaries

Periodic boundary conditions for plotting

Loading the raw data is slow

Loading of data

Checking the present data

API reference

xemc3 Dataset

xemc3.load module

xemc3.write module

Using xarray

Printing the dataset

Merging datasets

Configure xemc3

Using the with context manager

Simply setting it in the code

Setting it in ~/.local/xemc3/config.yaml

Custom filenames

Using a specific version

Ways to customise

Extending existing profiles

Extending all profiles

Custom profiles

Syntax

CLI reference

xemc3-append-time - CLI interface

xemc3-append-time positional arguments

xemc3-append-time optional arguments

xemc3-to-netcdf - CLI interface

xemc3-to-netcdf positional arguments

xemc3-to-netcdf optional arguments

xemc3-divertor - CLI interface

xemc3-divertor positional arguments

xemc3-divertor optional arguments

xemc3-to-archive - CLI interface

xemc3-to-archive positional arguments

xemc3-to-archive optional arguments

Citing xemc3

Installation

Indices and tables

Using the `with` context manager

Setting it in `~/.local/xemc3/config.yaml`