absSavTriCutCell

absSavTriCutCell

Works with VSimPD and VSimVE licenses.

This particle sink removes particles at a cut-cell (conformal) boundary, deleting them from the simulation, and (if requested) recording them. This sink absorbs particles on the triangulated surface (a set of triangles approximating the surface).

When possible (see below), this cut-cell sink calculates and records the exact time that particles cross the boundary, as well as the surface normal and grid cell. (Other cut-cell sinks currently do not do this.) This makes it possible, e.g., for secondaryEmitter to emit a secondary particle with the exact remaining time in the timestep. Thus a secondaryEmitter that preserves particle properties (but perhaps switches species) will not change a particle’s trajectory.

In principle, this sink removes particles that cross the surface into the absorber (specified by the gridBoundary and absorberIsInGridBoundary options). However, in some cases, the behavior is more complicated. If a particle is initially emitted inside the absorber, it typically gets one time step to escape the absorber; if it doesn’t escape, then the particle is absorbed at its initial location (which may not be near the absorber’s surface).

When recording absorbed particles, be aware that particles that are immediately absorbed after being secondary-emitted (based on previously-absorbed primary particles) may not be recorded as absorbed (hence further secondaries won’t be emitted). If this is a problem, it is in cases possible to fix it by making the secondary particles a different species.

absSavTriCutCell Parameters

minDim (integer, optional, default = 1)

Minimum dimensionality for which this sink is applicable (1, 2, or 3).

lowerBounds (integer vector)

Gives lower bounds of the particle sink in cell indices.

upperBounds (integer vector)

Gives upper bounds of the particle sink in cell indices.

gridBoundary (string)

Name of the gridBoundary that the describes the surface of absorption.

absorberIsInGridBoundary (boolean, optional, default = false)

Whether the absorbing material is the interior of the gridBoundary (if true), or in the exterior ( if false).

depositCurrentToCorner (boolean, optional, default = true)

This option should generally be true in electromagnetic simulations, especially for absorption at metallic (conducting) surfaces; it avoids the creation of artificial stationary charges. In electromagnetic simulation, absorbing a charge in the middle of a cell automatically leaves (or rather, leads to electromagnetic fields that act as if there were) a charge that remains at the emission location forever. If this option is true, then electrical current will be deposited from the absorption location to the nearest cell-corner that is inside the absorber.

recordParticleData (boolean, optional, default = true)

Whether absorbed particles should be recorded (either for use in Histories or for secondary emission). The record is cleared after each time step.

absorbLocation (string, optional, default = justOutsideAbsorber)

Where particles should be absorbed, when they are absorbed “at” the surface: justOutsideAbsorber, justInsideAbsorber, or nearestTheSurface (i.e., either inside or outside the absorber). In pathological cases, this request may not be honored.

recordAnomalous (bool, optional, default = true)

(This applies only if recordParticleData=true or recordParticleSumData=true.) Because of improper particle loading or (occasionally) finite precision discrepancies, a particle will be determined to be inside the absorber without have crossed the absorber surface. Such particles are removed from the simulation, but the absorption location may not be at the absorber surface, and therefore quantities such as the surface normal at the point of absorbtion (as well as angle of incidence, etc.) may not be determined for those particles. In some cases, it is desirable not to record these anomalously-absorbed particles; in these cases, one should set recordAnomalous=false. For example, if secondary emission is triggered by absorption, this would prevent secondary emission of particles within the absorber (away from the surface).

anomalousAbsorptionWarnMode (string, optional, default = never)

Anomalously absorbed particles are (usually pathological) particles that are detected in the sink/absorber (and sunk/removed), but were not detected crossing the surface into the absorber. As a result, it may be unknown exactly where the particle entered the absorber (hence what time it entered, what the surface normal was, etc.)

Depending on this attribute, warnings can be issued when that happens. Detailed warnings can be emitted for individual events, as well as warning summaries that report the number of warnings issued. See also the attributes anomalousAbsorptionWarnPeriodicity and anomalousAbsorptionWarnMaxDetails. The following values are valid (in order from least to most verbose).

never: Never emit warnings.

final: Warn summarily at end of simulation.

periodic: Emit warning summaries periodically (usually periodic in the timestep). These summaries require communication among all global MPI ranks, so issuing them every timestep might hurt performance (though it’s unlikely in most simulations). Issuing them every tenth or hundredth timestep is very unlikely to impact performance.

firstThenPeriodic: Emit a warning summary at the first opportunity (usually after the first timestep), and thereafter periodically.

immediateThenPeriodic: Emit individual detailed warnings immediately as they occur (without synchronizing among MPI ranks), but cease doing so after

anomalousAbsorptionWarnMaxDetails warnings are emitted (per rank). Warning summaries will be issued periodically.

immediate: Emit individual detailed warnings immediately as they occur (without synchronizing among MPI ranks); each rank will write warnings to its comms file, with only rank 0 outputting to the standard output. Warning summaries will be issued periodically. If there are many warnings, this option can degrade performance and result in significant disk usage (assuming the output is written to files). This option should be used only if it’s important to see every warning; it may especially useful if a simulation crashes before it has the opportunity to emit a warning summary.

immediateToStdout: All MPI ranks should emit individual warnings immediately to the standard output (if many ranks emit warnings, the output may be a mess). This should be used only in rare circumstances, and it should be with caution in large parallel simulations.

anomalousAbsorptionWarnPeriodicity (integer, optional, default = 10)

If anomalousAbsorptionWarnMode is set to issue warning summaries periodically, then this option specifies the period (usually in timesteps). If this is 0, then a summary will only be issued at the end of the simulation.

anomalousAbsorptionWarnMaxDetails (integer, optional, default = 1)

If anomalousAbsorptionWarnMode is set to issue warning summaries, this attribute specifies how many warnings to describe in detail (for each summary). Each MPI rank will always write details for warnings that occurred on that rank to its own comms file, with only rank 0 writing to the standard output. However, if rank 0 did not have any warnings (but other ranks did), details from other ranks will be written to the standard output.

saveDuringPtclEmissionStage (bool, optional, default = false)

(This applies only if recordParticleData=true or recordParticleSumData=true.) Whether particles should be saved (i.e., recorded) if they are absorbed immediately after being emitted. If this option is true, a simulation may become mired in an infinite loop or possibly even crash if, e.g., secondary emission occurs for absorbed particles. This option should generally be false unless it is important to record every absorbed particle and absorbing particles has no effect on an species (e.g., such as causing secondary emission).

ptclNotSavedWarnMode (string, optional, default = never)

If saveDuringPtclEmissionStage is false, then particles absorbed/sunk during the emission stage will not be saved/recorded. Depending on this attribute, warnings can be issued when that happens. Detailed warnings can be emitted for individual events, as well as warning summaries that report the number of warnings issued. See also the attributes ptclNotSavedWarnPeriodicity and ptclNotSavedWarnMaxDetails. The following values are valid (in order from least to most verbose).

never:

Never emit warnings.

final: Warn summarily at end of simulation.

periodic: Emit warning summaries periodically (usually periodic in the timestep). These summaries require communication among all global MPI ranks, so issuing them every timestep might hurt performance (though it’s unlikely in most simulations). Issuing them every tenth or hundredth timestep is very unlikely to impact performance.

firstThenPeriodic: Emit a warning summary at the first opportunity (usually after the first timestep), and thereafter periodically.

immediateThenPeriodic: Emit individual detailed warnings immediately as they occur (without synchronizing among MPI ranks), but cease doing so after ptclNotSavedWarnMaxDetails warnings are emitted (per rank). Warning summaries will be issued periodically.

immediate: Emit individual detailed warnings immediately as they occur (without synchronizing among MPI ranks); each rank will write warnings to its comms file, with only rank 0 outputting to the standard output. Warning summaries will be issued periodically. If there are many warnings, this option can degrade performance and result in significant disk usage (assuming the output is written to files). This option should be used only if it’s important to see every warning; it may especially useful if a simulation crashes before it has the opportunity to emit a warning summary.

immediateToStdout: All MPI ranks should emit individual warnings immediately to the standard output (if many ranks emit warnings, the output may be a mess). This should be used only in rare circumstances, and it should be with caution in large parallel simulations.

ptclNotSavedWarnPeriodicity (integer, optional, default = 10)

If ptclNotSavedWarnMode is set to issue warning summaries periodically, then this option specifies the period (usually in timesteps). If this is 0, then a summary will only be issued at the end of the simulation.

ptclNotSavedWarnMaxDetails (integer, optional, default = 1)

If ptclNotSavedWarnMode is set to issue warning summaries, this attribute specifies how many warnings to describe in detail (for each summary). Each MPI rank will always write details for warnings that occurred on that rank to its own comms file, with only rank 0 writing to the standard output. However, if rank 0 did not have any warnings (but other ranks did), details from other ranks will be written to the standard output.

useRelativeVelocity (string, default = false)

Set to true to have the absorber record relative velocities with respect to the absorber face. If false, the absolute velocities (i.e. the x, y, and z directional components) will be recorded instead.

absSavTriCutCell Example Block

<ParticleSink coneSurfSink>
  kind = absSavTriCutCell
  recordParticleData = true
  gridBoundary = coneSurf
  lowerBounds = [0 0 0]
  upperBounds = [8 8 8]
  depositCurrentToCorner = true
  useRelativeVelocity = true
</ParticleSink>