(green)¶

The type of output generated by this module is known by many names: Green’s functions, weight functions and response functions, to name just a few. We will henceforth use the former, Green’s function.

Mathematically, the Green’s function is defined as the function which, when integrated over phase space with the distribution function yields the detected radiation:

(1)¶\[I = \iiint G(\rho, p_\parallel, p_\perp) f(\rho, p_\parallel, p_\perp)\, p_\perp\, \mathrm{d}\rho\mathrm{d}p_\parallel\mathrm{d}p_\perp,\]

where \(G\) denotes the Green’s function, \(f\) the distribution function, and the lone factor of \(p_\perp\) at the end of the integrand is the momentum space Jacobian. More explicit expressions for \(G\) can be obtained from the synthetic radiation diagnostic integral (see the discussion on @Radiation), but for the sake of keeping the discussion we brief we will not give those details here.

An alternative definition of the Green’s function employed by some is to move the guiding-center Jacobian out of \(G\), so that \(G = J\tilde{G}\) and (1) instead reads

\[I = \iiint \tilde{G}(\rho, p_\parallel, p_\perp) f(\rho, p_\parallel, p_\perp)\, J\, p_\perp\, \mathrm{d}\rho\mathrm{d}p_\parallel\mathrm{d}p_\perp,\]

\(J\) is the Jacobian for the guiding-center transformation.

This output module allows you to consider many different types of Green’s functions, which may be integrated over any or all of phase space, the image pixels and/or the detector spectral range. It thus provides everything needed to analyse the phase space dependence of detected radiation, or attempt to solve an inverse problem.

Summary of options¶

Option	Description
`@RadiationOutput(green) common`	List of common quantities to include in the output file.
`@RadiationOutput(green) f_as_linear_array`	Store the output function as a linear array.
`@RadiationOutput(green) format`	Green’s function format (i.e. dependences).
`@RadiationOutput(green) mpi_mode`	How to generate the Green’s function.
`@RadiationOutput(green) output`	Name of output file.
`@RadiationOutput(green) pixels`	Number of pixels.
`@RadiationOutput(green) stokesparams`	Whether or not to store Stokes parameters.
`@RadiationOutput(green) suboffseti`	Sub-image offset in vertical direction.
`@RadiationOutput(green) suboffsetj`	Sub-image offset in horizontal direction.
`@RadiationOutput(green) subpixels`	Number of pixels in sub-image.
`@RadiationOutput(green) with_f`	Multiply with the distribution function.
`@RadiationOutput(green) with_jacobian`	Multiply with the guiding-center Jacobian.

Example configuration¶

The following example generates a Green’s function with one radial dimension and two pixel dimensions, allowing various radial density profiles to be applied after the simulation to generate the corresponding radiation images:

@RadiationOutput ourOutput (green) {
    format = "rij";
    output = "/path/to/output.mat";
    pixels = 300 300;
}

Output file structure¶

The output file always contains the following variables:

Option	Description
`colpixels`	(Only if image dimension `j` is part of the function) The number of column pixels.

`func`	Array containing the Green’s function.
`rowpixels`	(Only if image dimension `i` is part of the function) The number of row pixels.

`stokesparams`	Set to `1` if the Green’s function contains the four Stokes parameters.

`type`	Green’s function format string.
`wavelengths`	Spectrum grid (wavelength for synchrotron, photon energy normalized to electron rest mass for bremsstrahlung).

Common quantities¶

By default, the following “common quantities” are also included in the output file:

Name	Description
`domain`	Tokamak wall or separatrix (depending on which was used).
`param1`	First momentum parameter grid.
`param2`	Second momentum parameter grid.
`param1name`	SOFT name of first momentum parameter.
`param2name`	SOFT name of second momentum parameter.
`r`	Radial grid.

For details about which other common quantities can be included in the output, please consult the page about the @RadiationOutput class of modules.

Subset images¶

Green’s functions can become very large if pixel information is desired. To reduce the amount of unnecessary information stored, it is possible to only store a certain part of a camera image, i.e. a subset image.

The subset image is defined by three parameters:

Offset in the vertical direction (@RadiationOutput(green) suboffseti)
Offset in the horizontal direction (@RadiationOutput(green) suboffsetj)
Number of pixels of subset image (@RadiationOutput(green) subpixels).

In the illustration above, these parameters are suboffseti = 3, suboffsetj = 4 and subpixels = 3.

Note

The sums suboffseti + subpixels(i) and suboffsetj + subpixels(j) must both be less than or equal to the value assigned to* @RadiationOutput(green) pixels.

MPI Mode¶

When running with MPI, Green’s functions can be generated and stored in two different ways. These two different modes of generation are referred to as contiguous mode and chunked mode, due to the way the function is stored on disk in each.

Contiguous mode¶

In this mode, the Green’s function will be stored in a single file on disk. Phase space is always divided among the MPI processes, but when all MPI processes have carried out all computations for their parts of phase space, the individual Green’s functions are combined into a single function in the root process, which is then written to a single file.

This mode is useful when the purpose for running with MPI is to further parallelize and speed up the computation. The total amount of memory required is equal to the size of the final Green’s function, multiplied by the number of MPI processes and the number of threads per process. This mode can therefore be very memory-intensive.

Chunked mode¶

In chunked mode, each MPI process generates its own output file, containing a part of the full Green’s function. The various parts of the Green’s function can then be processed individually and combined to form a full function.

What part of the Green’s function each chunk corresponds to depends on how phase space was divided among the MPI processes, i.e. how the @ParticleGenerator mpi_distribute_mode parameter was set. If, for example, mpi_distribute_mode was set to radius, then each chunk will correspond to the radial interval processed by the MPI process that generated the chunk. Note that this means that the parameter which is divided among the MPI processes must be a part of the Green’s function.

In this mode, the output file name is specified as usual, i.e. as if only one single file were to be created. Each MPI process will then insert an index corresponding to its rank just before the file extension. Setting @RadiationOutput(green) output to ourFile.mat in chunked mode will thus result in a number of files with names ourFile0.mat, ourFile1.mat etc. being generated. MPI ranks are zero-indexed, and thus the output files are so too.

This mode is useful when generating very large Green’s functions, as it allows you take advantage of the large amount of total memory offered by distributed memory systems. To maximize the amount of memory available for the Green’s function in a simulation, set global num_threads to 1 (i.e. one thread per MPI process). This will significantly slow down the simulation, but since each thread stores its own copy of the Green’s function, it will also significantly reduce the memory usage of SOFT.

All options¶

common¶

Default value:	`none`
Allowed values:	See the list on @RadiationOutput.

Specifies which “common quantities” to include in the output file. A full list of possible options is given on @RadiationOutput.

f_as_linear_array¶

Default value:	`no`
Allowed values:	`yes` and `no`

If yes, then func is stored as a linear array (i.e. 1-by-many matrix) instead of the default multi-dimensional format. In this mode, the array must therefore be reshaped to have the correct number of dimensions. In Matlab, this is done by calling reshape(func, [nN, nN_1, ..., n1]), where func is the Green’s function, nN is the number of elements in the last dimension of the function, nN_1 the number of elements in the next-to-last dimension etc. Thus, if the @RadiationOutput(green) format option is set to rij, then the appropriate Matlab command would be:

reshape(func, [ni, nj, nr])

In Python, on the other hand, the order of the dimensions is reversed, so that the equivalent code reads:

import numpy as np
np.reshape(func, (nr, nj, ni))

Note

By default, @RadiationOutput(green) f_as_linear_array is set to no, meaning that the Green’s function is reshaped internally by SOFT before being written to file. Thus, by default, no reshape is required.

This default is new since 2019-04-02.

format¶

Default value:	Nothing
Allowed values:	Any combination of `1`, `2`, `i`, `j`, `r` and `w`.

Specifies the format of the Green’s function, i.e. which parameters the function should depend on and in which order the dependences should be placed. The format is a string consisting of any number of the characters in the table below, in any order.

For example, if @RadiationOutput(green) format is set to r12, the Green’s function \(G(\rho, p_1, p_2)\) will be generated, where \(p_1\) and \(p_2\) denote the momentum space parameters used for the simulation (specified in the @ParticleGenerator module; the momentum parameters are ordered alphabetically, so that \(p_1\) is the momentum parameter which’s name comes first alphabetically). The function \(G(\rho, p_1, p_2)\) will be represented as a 3-dimensional array with the \(\rho\) dependence along the first dimension, \(p_1\) dependence along the second dimension, and \(p_2\) along the third.

Format	Description
`1`	(Alphabetically) first momentum parameter.
`2`	(Alphabetically) second momentum parameter.
`i`	Vertical pixel dimension.
`j`	Horizontal pixel dimension.
`r`	Radial parameter.
`w`	Radiation spectrum.

Note

For pixels, both i and j must specified; they may be specified in any order though.

mpi_mode¶

Default value:	`contiguous`
Allowed values:	`chunked` and `contiguous`

When SOFT2 is compiled with MPI, specifies how the Green’s function is to be generated and stored. See the discussion above about the MPI Mode for details above the two available modes.

output¶

Default value:	Nothing
Allowed values:	Any valid file name.

Name of the output file in which to store the result.

pixels¶

Default value:	0
Allowed values:	Any positive integer.

Number of pixels in image (if i and j are part of the format string). If only one value is specified, the image becomes quadratic with the same number of pixels in both the vertical and horizontal directions. If two values are given, the first value is interpreted as the number of pixels in the vertical direction and second value as the number of pixels in the horizontal direction.

stokesparams¶

Default value:	`no`
Allowed values:	`yes` or `no`.

If yes, adds information about the Stokes parameter \((I, Q, U, V)\) to the Green’s function. Another dimension is added to the output array, and becomes the new first dimension. This effectively means that instead of storing one Green’s function, four separate Green’s function corresponding to each of the Stokes parameters is stored contiguously in memory.

suboffseti¶

suboffsetj¶

Default value:	0
Allowed values:	Any non-negative integer.

Specifies the vertical and horizontal offset, respectively, of the subset image.

subpixels¶

Default value:	Same as `@RadiationOutput(green) pixels`
Allowed values:	Any positive integer.

Specifies the number of pixels of the subset image. If only one value is specified, the subset image becomes quadratic with the same number of pixels in both the vertical and horizontal directions. If two values are given, the first value is interpreted as the number of pixels in the vertical direction and the second value as the number of pixels in the horizontal direction.

with_f¶

Default value:	`no`
Allowed values:	`yes` or `no`.

If yes, multiplies the Green’s function with the distribution function. This allows the (green) module to produce proper radiation quantities, such as camera images or Dominant particles.

Note

If this option is enabled, the momentum space Jacobian will still NOT be multiplied with the result, and must be applied manually.

with_jacobian¶

Default value:	`yes`
Allowed values:	`yes` or `no`

If yes, includes the guiding-center in the definition of the Green’s function (i.e. generates \(G\), as defined at the top of this page).