Header file for particle.c. More...

#include "ascot5.h"
#include "B_field.h"
#include "E_field.h"
#include "error.h"

Data Structures
struct	particle_state
	General representation of a marker. More...

struct	particle
	Particle input. More...

struct	particle_gc
	Guiding center input. More...

struct	particle_ml
	Field line input. More...

struct	particle_queue
	Marker queue. More...

struct	input_particle
	Wrapper for marker structs. More...

struct	particle_simd_fo
	Struct representing NSIMD particle markers. More...

struct	particle_simd_gc
	Struct representing NSIMD guiding center markers. More...

struct	particle_simd_ml
	Struct representing NSIMD field line markers. More...

Typedefs
typedef enum input_particle_type	input_particle_type
	Marker types enum.

Enumerations
enum	input_particle_type { input_particle_type_p , input_particle_type_gc , input_particle_type_ml , input_particle_type_s }
	Marker types enum. More...

Functions
void	particle_allocate_fo (particle_simd_fo *p_fo, int nmrk)
	Allocates struct representing particle markers.

void	particle_to_fo_dummy (particle_simd_fo *p_fo, int j)
	Makes a dummy FO simulation marker.

void	particle_to_gc_dummy (particle_simd_gc *p_gc, int j)
	Makes a dummy GC simulation marker.

void	particle_to_ml_dummy (particle_simd_ml *p_ml, int j)
	Makes a dummy ML simulation marker.

int	particle_cycle_fo (particle_queue q, particle_simd_fo p, B_field_data Bdata, int cycle)
	Replace finished FO markers with new ones or dummies.

int	particle_cycle_gc (particle_queue q, particle_simd_gc p, B_field_data Bdata, int cycle)
	Replace finished GC markers with new ones or dummies.

int	particle_cycle_ml (particle_queue q, particle_simd_ml p, B_field_data Bdata, int cycle)
	Replace finished ML markers with new ones or dummies.

void	particle_input_to_state (input_particle p, particle_state ps, B_field_data *Bdata)
	Converts input marker to a marker state.

a5err	particle_input_p_to_state (particle p, particle_state ps, B_field_data *Bdata)
	Convert an input particle marker to particle state.

a5err	particle_input_gc_to_state (particle_gc p, particle_state ps, B_field_data *Bdata)
	Convert an input guiding center marker to particle state.

a5err	particle_input_ml_to_state (particle_ml p, particle_state ps, B_field_data *Bdata)
	Convert an input field line marker to particle state.

void	particle_offload_fo (particle_simd_fo *p)
	Offload particle struct to GPU.

a5err	particle_state_to_fo (particle_state p, int i, particle_simd_fo p_fo, int j, B_field_data *Bdata)
	Convert state into a FO SIMD marker.

void	particle_fo_to_state (particle_simd_fo p_fo, int j, particle_state p, B_field_data *Bdata)
	Convert FO to state.

a5err	particle_state_to_gc (particle_state p, int i, particle_simd_gc p_gc, int j, B_field_data *Bdata)
	Convert state into a GC SIMD marker.

void	particle_gc_to_state (particle_simd_gc p_gc, int j, particle_state p, B_field_data *Bdata)
	Convert GC to state.

a5err	particle_state_to_ml (particle_state p, int i, particle_simd_ml p_ml, int j, B_field_data *Bdata)
	Convert state to a ML SIMD marker.

void	particle_ml_to_state (particle_simd_ml p_ml, int j, particle_state p, B_field_data *Bdata)
	Convert ML to state.

int	particle_fo_to_gc (particle_simd_fo p_fo, int j, particle_simd_gc p_gc, B_field_data *Bdata)
	Convert FO struct into a GC struct.

GPU_DECLARE_TARGET_SIMD void	particle_copy_fo (particle_simd_fo p1, int i, particle_simd_fo p2, int j)
	Copy FO struct.

DECLARE_TARGET_END DECLARE_TARGET_SIMD void	particle_copy_gc (particle_simd_gc p1, int i, particle_simd_gc p2, int j)
	Copy GC struct.

DECLARE_TARGET_SIMD void	particle_copy_ml (particle_simd_ml p1, int i, particle_simd_ml p2, int j)
	Copy ML struct.

Detailed Description

Header file for particle.c.

The relationship between the seven different marker structs is:

particle >–+ +--> particle_simd_fo | | particle_gc >–particle_state--> particle_simd_gc | | particle_ml >–+ +--> particle_simd_ml

which is explained in particle.c. This file contains the definitions of these structs as well as input_particle and particle_queue structs. Former is a wrapper for particle, particle_gc, particle_ml, and particle_state structs while latter is a queue from where markers are chosen when simulation begins and updated when simulation ends.

Definition in file particle.h.

Typedef Documentation

◆ input_particle_type

typedef enum input_particle_type input_particle_type

Marker types enum.

Used to indicate what marker type is stored in input_particle wrapper.

Enumeration Type Documentation

◆ input_particle_type

enum input_particle_type

Marker types enum.

Used to indicate what marker type is stored in input_particle wrapper.

Enumerator
input_particle_type_p	Type corresponding to particle struct
input_particle_type_gc	Type corresponding to particle_gc struct
input_particle_type_ml	Type corresponding to particle_ml struct
input_particle_type_s	Type corresponding to particle_state struct

Definition at line 168 of file particle.h.

Function Documentation

◆ particle_allocate_fo()

void particle_allocate_fo	(	particle_simd_fo *	p_fo,
		int	nmrk )

Allocates struct representing particle markers.

Size used for memory allocation is NSIMD for CPU run and the total number of particles for GPU.

Parameters

p_fo	marker struct to allocate
nmrk	the number of markers that the struct represents

Definition at line 69 of file particle.c.

◆ particle_to_fo_dummy()

void particle_to_fo_dummy	(	particle_simd_fo *	p_fo,
		int	j )

Makes a dummy FO simulation marker.

A dummy marker is a marker whose fields have possible but unrealistic values. It is intended to act as a filler for SIMD arrays that would otherwise be left uninitialized.

A dummy marker has negative one (-1) ID and negative one (-1) queue index, and it is not running (0). Dummy marker should be ignored when encountered during the simulation.

Parameters

p_fo	pointer to particle_simd_fo array where dummy is placed
j	index of the new dummy in the SIMD arrays

Definition at line 132 of file particle.c.

◆ particle_to_gc_dummy()

void particle_to_gc_dummy	(	particle_simd_gc *	p_gc,
		int	j )

Makes a dummy GC simulation marker.

A dummy marker is a marker whose fields have possible but unrealistic values. It is intended to act as a filler for SIMD arrays that would otherwise be left uninitialized.

A dummy marker has negative one (-1) ID and negative one (-1) queue index, and it is not running (0). Dummy marker should be ignored when encountered during the simulation.

Parameters

p_gc	pointer to particle_simd_gc array where dummy is placed
j	index of the new dummy in the SIMD arrays

Definition at line 172 of file particle.c.

◆ particle_to_ml_dummy()

void particle_to_ml_dummy	(	particle_simd_ml *	p_ml,
		int	j )

Makes a dummy ML simulation marker.

A dummy marker is a marker whose fields have possible but unrealistic values. It is intended to act as a filler for SIMD arrays that would otherwise be left uninitialized.

A dummy marker has negative one (-1) ID and negative one (-1) queue index, and it is not running (0). Dummy marker should be ignored when encountered during the simulation.

Parameters

p_ml	pointer to particle_simd_ml array where dummy is placed
j	index of the new dummy in the SIMD arrays

Definition at line 218 of file particle.c.

◆ particle_cycle_fo()

int particle_cycle_fo	(	particle_queue *	q,
		particle_simd_fo *	p,
		B_field_data *	Bdata,
		int *	cycle )

Replace finished FO markers with new ones or dummies.

A marker has finished simulation when marker.running = 0. If queue has unsimulated markers, one is picked to replace the finished marker. If not, a dummy marker is used as a replacement instead. Finished marker is converted to marker state and stored in the queue.

This function updates queue.next and queue.finished fields when a marker has finished simulation. This is done thread-safe.

This function returns values indicating what was done for each marker in a SIMD array: 0 : Nothing -1 : Finished marker replaced with a dummy (queue is empty) 1 : Finished marker replaced with a fresh one

Parameters

q	pointer to marker queue
p	pointer to SIMD structure of markers
Bdata	pointer to magnetic field data
cycle	pointer to integer array where what was done for each marker is stored

Returns: Number of markers within the SIMD structure that are still running

Definition at line 268 of file particle.c.

◆ particle_cycle_gc()

int particle_cycle_gc	(	particle_queue *	q,
		particle_simd_gc *	p,
		B_field_data *	Bdata,
		int *	cycle )

Replace finished GC markers with new ones or dummies.

A marker has finished simulation when marker.running = 0. If queue has unsimulated markers, one is picked to replace the finished marker. If not, a dummy marker is used as a replacement instead. Finished marker is converted to marker state and stored in the queue.

This function updates queue.next and queue.finished fields when a marker has finished simulation. This is done thread-safe.

This function returns values indicating what was done for each marker in a SIMD array: 0 : Nothing -1 : Finished marker replaced with a dummy (queue is empty) 1 : Finished marker replaced with a fresh one

Parameters

q	pointer to marker queue
p	pointer to SIMD structure of markers
Bdata	pointer to magnetic field data
cycle	pointer to integer array where what was done for each marker is stored

Returns: Number of markers within the SIMD structure that are still running

Definition at line 367 of file particle.c.

◆ particle_cycle_ml()

int particle_cycle_ml	(	particle_queue *	q,
		particle_simd_ml *	p,
		B_field_data *	Bdata,
		int *	cycle )

Replace finished ML markers with new ones or dummies.

A marker has finished simulation when marker.running = 0. If queue has unsimulated markers, one is picked to replace the finished marker. If not, a dummy marker is used as a replacement instead. Finished marker is converted to marker state and stored in the queue.

This function updates queue.next and queue.finished fields when a marker has finished simulation. This is done thread-safe.

This function returns values indicating what was done for each marker in a SIMD array: 0 : Nothing -1 : Finished marker replaced with a dummy (queue is empty) 1 : Finished marker replaced with a fresh one

Parameters

q	pointer to particle queue
p	pointer to SIMD structure of markers
Bdata	pointer to magnetic field data
cycle	pointer to integer array where what was done for each marker is stored

Returns: Number of markers within the SIMD structure that are still running

Definition at line 461 of file particle.c.

◆ particle_input_to_state()

void particle_input_to_state	(	input_particle *	p,
		particle_state *	ps,
		B_field_data *	Bdata )

Converts input marker to a marker state.

When marker input is read, the data is stored in one of the input marker structs (particle, particle_gc, particle_ml). This function converts these structs into a marker state, which then can be used to create simulation structs.

If an error is encountered while converting, the error message is stored to the state.

Todo

Parameter p can be a particle_state itself but this option is not dealt with

This sets p->type = input_particle_type_s which is not in accordance with the documentation.

Parameters

p	pointer to marker input
ps	pointer to state where converted marker will be stored
Bdata	pointer to magnetic field data

Definition at line 550 of file particle.c.

◆ particle_input_p_to_state()

a5err particle_input_p_to_state	(	particle *	p,
		particle_state *	ps,
		B_field_data *	Bdata )

Convert an input particle marker to particle state.

Parameters

p	pointer to particle marker input
ps	pointer to state where converted marker will be stored
Bdata	pointer to magnetic field data

Returns: zero if there was no error

Definition at line 1449 of file particle.c.

◆ particle_input_gc_to_state()

a5err particle_input_gc_to_state	(	particle_gc *	p,
		particle_state *	ps,
		B_field_data *	Bdata )

Convert an input guiding center marker to particle state.

Parameters

p	pointer to guiding center marker input
ps	pointer to state where converted marker will be stored
Bdata	pointer to magnetic field data

Returns: zero if there was no error

Definition at line 1540 of file particle.c.

◆ particle_input_ml_to_state()

a5err particle_input_ml_to_state	(	particle_ml *	p,
		particle_state *	ps,
		B_field_data *	Bdata )

Convert an input field line marker to particle state.

Parameters

p	pointer to field line marker input
ps	pointer to state where converted marker will be stored
Bdata	pointer to magnetic field data

Returns: zero if there was no error

Definition at line 1656 of file particle.c.

◆ particle_offload_fo()

void particle_offload_fo ( particle_simd_fo * p )

Offload particle struct to GPU.

Parameters

p	pointer to the particle struct to be offloaded.

Definition at line 1726 of file particle.c.

◆ particle_state_to_fo()

a5err particle_state_to_fo	(	particle_state *	p,
		int	i,
		particle_simd_fo *	p_fo,
		int	j,
		B_field_data *	Bdata )

Convert state into a FO SIMD marker.

This function assumes markers are drawn from a marker queue where they will be returned at the same position once simulation for this marker has ended,

State is converted into a FO marker by copying all the fields, except for magnetic field (and rho) which is evaluated here at FO position and then stored.

The simulation marker is set as running unless there is an error or the state already have active end condition.

If state marker already has an error flag, this error flag is returned and nothing is done. If an error occurs within this function, the conversion is terminated and the error is returned. It is the responsibility of the caller to store the error in correct struct.

This is a SIMD function.

Parameters

p	pointer to a state being converted
i	index of this state in the marker queue
p_fo	pointer to SIMD structure where marker is being stored
j	index where in the SIMD structure marker is stored
Bdata	pointer to magnetic field data

Definition at line 659 of file particle.c.

◆ particle_fo_to_state()

void particle_fo_to_state	(	particle_simd_fo *	p_fo,
		int	j,
		particle_state *	p,
		B_field_data *	Bdata )

Convert FO to state.

This function converts FO simulation marker to a marker state. No new state structure is initialized, but an existing one is filled with parameters corresponding to the converted marker.

This is a SIMD function.

Parameters

p_fo	pointer to SIMD structure
j	SIMD index of the marker to be converted
p	pointer to state whose fields are used to store the converted marker
Bdata	pointer to magnetic field data

Definition at line 744 of file particle.c.

◆ particle_state_to_gc()

a5err particle_state_to_gc	(	particle_state *	p,
		int	i,
		particle_simd_gc *	p_gc,
		int	j,
		B_field_data *	Bdata )

Convert state into a GC SIMD marker.

This function assumes markers are drawn from a marker queue where they will be returned at the same position once simulation for this marker has ended,

State is converted into a GC marker by simply copying all the necessary fields.

The simulation marker is set as running unless there is an error or the state already have active end condition.

If state marker already has an error flag, this error flag is returned and nothing is done. If an error occurs within this function, the conversion is terminated and the error is returned. It is the responsibility of the caller to store the error in correct struct.

This is a SIMD function.

Parameters

p	pointer to a state being converted
i	index of this state in the marker queue
p_gc	pointer to SIMD structure where marker is being stored
j	index where in the SIMD structure marker is stored
Bdata	pointer to magnetic field data

Definition at line 871 of file particle.c.

◆ particle_gc_to_state()

void particle_gc_to_state	(	particle_simd_gc *	p_gc,
		int	j,
		particle_state *	p,
		B_field_data *	Bdata )

Convert GC to state.

This function converts GC simulation marker to a marker state. No new state structure is initialized, but an existing one is filled with parameters corresponding to the converted marker.

This is a SIMD function.

Parameters

p_gc	pointer to SIMD structure
j	SIMD index of the marker to be converted
p	pointer to state whose fields are used to store the converted marker
Bdata	pointer to magnetic field data

Definition at line 936 of file particle.c.

◆ particle_state_to_ml()

a5err particle_state_to_ml	(	particle_state *	p,
		int	i,
		particle_simd_ml *	p_ml,
		int	j,
		B_field_data *	Bdata )

Convert state to a ML SIMD marker.

This function assumes markers are drawn from a marker queue where they will be returned at the same position once simulation for this marker has ended,

State is converted into a ML marker by using particle position as initial position. Other fields are simply copied exceot pitch, which is calculated from vpar as pitch = 2*(vpar >= 0) - 1, i.e., sign of vpar determines sign of pitch.

The simulation marker is set as running unless there is an error or the state already have active end condition.

If state marker already has an error flag, this error flag is returned and nothing is done. If an error occurs within this function, the conversion is terminated and the error is returned. It is the responsibility of the caller to store the error in correct struct.

This is a SIMD function.

Todo: A minor thing but it would be better if guiding center position were used instead. This would require evaluation of the magnetic field.

Parameters

p	pointer to a state being converted
i	index of this state in the marker queue
p_ml	pointer to SIMD structure where marker is being stored
j	index where in the SIMD structure marker is stored
Bdata	pointer to magnetic field data

Definition at line 1052 of file particle.c.

◆ particle_ml_to_state()

void particle_ml_to_state	(	particle_simd_ml *	p_ml,
		int	j,
		particle_state *	p,
		B_field_data *	Bdata )

Convert ML to state.

This function converts ML simulation marker to a marker state. No new state structure is initialized, but an existing one is filled with parameters corresponding to the converted marker.

Field line position is stored in both particle and guiding center position fields. Direction is stored in vpar field. rdot, phidot, zdot, mu, zeta, mass, and charge are left empty.

This is a SIMD function.

Parameters

p_ml	pointer to SIMD structure
j	SIMD index of the marker to be converted
p	pointer to state whose fields are used to store the converted marker
Bdata	pointer to magnetic field data

Definition at line 1117 of file particle.c.

◆ particle_fo_to_gc()

int particle_fo_to_gc	(	particle_simd_fo *	p_fo,
		int	j,
		particle_simd_gc *	p_gc,
		B_field_data *	Bdata )

Convert FO struct into a GC struct.

Deprecated: Do we need this as same can be accomplished by turning FO to state and state to GC?

Parameters

p_fo	fo SIMD structure being transformed
j	index where in the SIMD structure marker is stored
p_gc	gc SIMD structure where marker is transformed
Bdata	pointer to magnetic field data

Definition at line 1185 of file particle.c.

◆ particle_copy_fo()

GPU_DECLARE_TARGET_SIMD void particle_copy_fo	(	particle_simd_fo *	p1,
		int	i,
		particle_simd_fo *	p2,
		int	j )

Copy FO struct.

Parameters

p1	SIMD structure for input
i	index for the copied input
p2	SIMD structure for output
j	index for the output slot

Definition at line 1302 of file particle.c.

◆ particle_copy_gc()

DECLARE_TARGET_END DECLARE_TARGET_SIMD void particle_copy_gc	(	particle_simd_gc *	p1,
		int	i,
		particle_simd_gc *	p2,
		int	j )

Copy GC struct.

Parameters

p1	SIMD structure for input
i	index for the copied input
p2	SIMD structure for output
j	index for the output slot

Definition at line 1355 of file particle.c.

◆ particle_copy_ml()

DECLARE_TARGET_SIMD void particle_copy_ml	(	particle_simd_ml *	p1,
		int	i,
		particle_simd_ml *	p2,
		int	j )

Copy ML struct.

Parameters

p1	SIMD structure for input
i	index for the copied input
p2	SIMD structure for output
j	index for the output slot

Definition at line 1404 of file particle.c.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ input_particle_type

Enumeration Type Documentation

◆ input_particle_type

Function Documentation

◆ particle_allocate_fo()

◆ particle_to_fo_dummy()

◆ particle_to_gc_dummy()

◆ particle_to_ml_dummy()

◆ particle_cycle_fo()

◆ particle_cycle_gc()

◆ particle_cycle_ml()

◆ particle_input_to_state()

◆ particle_input_p_to_state()

◆ particle_input_gc_to_state()

◆ particle_input_ml_to_state()

◆ particle_offload_fo()

◆ particle_state_to_fo()

◆ particle_fo_to_state()

◆ particle_state_to_gc()

◆ particle_gc_to_state()

◆ particle_state_to_ml()

◆ particle_ml_to_state()

◆ particle_fo_to_gc()

◆ particle_copy_fo()

◆ particle_copy_gc()

◆ particle_copy_ml()