m_tracers.py

class m_tracers.Tracers(MeshClass, ElemClass, FilesClass)

Bases: object

Class that contains functions related to initial distribution, addition, advection and removal of the particle tracers.

add_tracers(t, step)

When number of tracers in an element drops below a critical level (defined within), new tracers will be added to ensure that the element will always contain some tracers. The physical properties are assigned from the value at the element.

Note

Tracers are not added if:

  • the composition of the element is mixed (tracer can have only one composition) and adding would violate the mass conservation.

  • there is a part of the domain specified by allow_empty_cells = True and empty_region

Caution

Under some circumstances, a cell might loose all the tracers during one time step (e.g., when the surface topography moves too quickly during one time step) and the tracers are then added in the same manner as above. These cases are rare, though undesirable, therefore occuremce of empty cells is monitored in each time step and recorded in data_*/empty_cells.dat.

add_tracers_unstructured()
advect_tracers(v, v_mesh, dt)

Advects the tracers by the velocity field using the 2nd or 4th-order Runge-Kutta integration scheme (see integration_method in m_parameters.py). Each process advects the tracers that lie within its part of the domain.

Parameters:

  • v – flow velocity

  • v_mesh – mesh deformation velocity (serves to anticipate the mesh motion)

  • dt – time step length

Note

The tracers can be advected succesfully by this function only if the position before and after the advection lies in the same rank. If the advection fails at any point of the integration scheme, the tracer is passed to a function m_tracers.Tracers.find_tracers().

check_tracers()

Checks whether the number of the tracers in the tracers lists (corrected for empty places called vacancy) matches with the total sum of the tracers in the cells.

delete_and_find()

When a tracer moves from one rank to another, this function deletes it from the tracers list, leaving an unoccupied position []. The index of this position is entered to the vacancy list and new tracers will be added there preferentially over adding them at the end of the tracers list (which protects the list from unconstrained growth). Finally, for the moving tracer, the rank and cell where it newly belongs is found and the tracer is added to the tracers list of the respective rank.

find_tracers(v, dt)

Advects the tracers that changed the rank during the advection (i.e., could not be advected by m_tracers.Tracers.advect_tracers()) by the velocity field using the 2nd or 4th-order Runge-Kutta integration scheme.

Parameters:

  • v – flow velocity

  • dt – time step length

introduce_tracers()

At the beginning of the simulation, this function

  • distributes the tracers regularly into the elements

  • assignes the cell number (j) to a corresponding tracer

  • assignes the tracer number (its position within the tracers array) to a corresponding cell tracers_in_cell

Each tracer carries the following properties

# --- Create an ID that will be unique ---
unique_ID = tracer_no*size + rank

self.tracers.append([x_pos, y_pos, j, rank, 0.0, 0.0, 0.0, y_pos, comp, [0.0, 0.0], 0.0, unique_ID])

# --- Essential for advection of tracers ---
# 0) x-position                     
# 1) y-position                     
# 2) cell where the tracer is         
# 3) rank where the tracer is

# --- Quantities to be advected ---
# 4) tau_xx
# 5) tau_xz
# 6) plastic strain
# 9) original depth of the tracer
# 10) composition [mat1, mat2, ...]
# 11) [melt fraction, delta_T]
# 12) tracer original (0) or added (1)
# 13) unique tracer ID
introduce_tracers_unstructured()

Similar as introduce_tracers(), but for a non-rectangular mesh, i.e. when it is deformed by initial conditions.

load_tracers()

If the simulation is being restarted from a saved checkpoint (reload_tracers = True with reload_name and reload_tracers_step specified), this function loads tracers from a given file located in the respective directory.

rank_interpolation()

Assigns the rank of the process to the function mesh_ranks.

Tip

This function is useful to visualize which process covers which part of the computational domain.

save_header_tracer(file)

Saves the header for the tracer data files in data_*/tracetrs/step_*.txt. Inputs for the header are given in the Tracers_header list.

save_indiv_tracer(file, j, **kwargs)

Saves the variables carried by an individual tracer. The tracer’s x and y coordinates are saved by default, other are specified in the Tracers_Output list.

save_tracers(step)

Saves the tracers in a dedicated directory data_*/tracers/step_*.dat.

tracer_count_interpolation()

Counts the number of tracers inside an element and assigns it to the dunction number_of_tracers.