Nonlocal Couplings
The purpose of a model is often to compute the sum, average, maximum value, or minimum value of a quantity over a group of particles, such as the average kinetic energy or the maximum residence time. A particle tracing interface with Name <phys> (usually pt, cpt, or fpt depending on the interface) creates the following operators:
The built-in nonlocal coupling names have recently changed, but the couplings with the old names are still available. In their descriptions the couplings with the old names are marked as “deprecated”. Both the old and new names are listed in Table 2-2.
•
<phys>.sum(expr) evaluates the sum of the expression expr over the particles. The sum includes all particles that are active, frozen, or stuck to boundaries. It excludes particles that have not yet been released and those that have disappeared.
•
<phys>.sum_all(expr) evaluates the sum of the expression expr over all particles, including particles those that are not yet released or have disappeared. Since the coordinates of unreleased and disappeared particles are not-a-number (NaN), the sum may return NaN if the model includes unreleased or disappeared particles. An expression such as pt.sum_all(isnan(qx)) can be used to compute the total number of unreleased and disappeared particles.
•
<phys>.ave(expr) evaluates the average of the expression expr over the active, frozen, and stuck particles. Unreleased and disappeared particles contribute to neither the numerator nor the denominator of the arithmetic mean.
•
<phys>.ave_all(expr) evaluates the average of the expression expr over all particles. It is likely to return NaN if the model includes unreleased or disappeared particles.
•
<phys>.max(expr) evaluates the maximum value of the expression expr over all active, frozen, and stuck particles.
•
<phys>.max_all(expr) evaluates the maximum value of the expression expr over all particles.
The treatment of NaN values in nonlocal maximum couplings can be platform-dependent, so use caution when evaluating the maximum over all particles including disappeared and unreleased particles.
•
<phys>.min(expr) evaluates the minimum value of the expression expr over the active, frozen, and stuck particles.
•
<phys>.min_all(expr) evaluates the minimum value of the expression expr over all particles.
The treatment of NaN values in nonlocal minimum couplings can be platform-dependent, so use caution when evaluating the minimum over all particles including disappeared and unreleased particles.
•
<phys>.max(expr, evalExpr) evaluates the expression evalExpr for the particle that has the maximum value of the expression expr out of all active, frozen, and stuck particles. For example, in a model that uses the Mathematical Particle Tracing interface with name pt, the expression pt.max(pt.V, qx) would evaluate the x-coordinate qx of the particle with the greatest velocity magnitude pt.V.
•
<phys>.max_all(expr, evalExpr) evaluates the expression evalExpr for the particle that has the maximum value of the expression expr for all particles, including disappeared and unreleased particles.
•
<phys>.min(expr, evalExpr) evaluates the expression evalExpr for the particle that has the minimum value of the expression expr out of all active, frozen, and stuck particles. For example, in a model that uses the Mathematical Particle Tracing interface with name pt, the expression pt.min(pt.V, qx) would evaluate the x-coordinate qx of the particle with the smallest velocity magnitude pt.V.
•
<phys>.min_all(expr, evalExpr) evaluates the expression evalExpr for the particle that has the minimum value of the expression expr for all particles, including disappeared and unreleased particles.
An instance of the Mathematical Particle Tracing interface with the default name pt defines the built-in nonlocal couplings shown in Table 2-2.
 
Table 2-2: Built-in Nonlocal couplings for the Mathematical Particle Tracing Interface
Coupling Name
Deprecated Name
Description
pt.sum(a)
pt.ptop1(a)
Sum over particles
pt.sum_all(a)
pt.ptop_all1(a)
Sum over all particles
pt.ave(a)
pt.ptaveop1(a)
Average over particles
pt.ave_all(a)
pt.ptaveop_all1(a)
Average over all particles
pt.max(a)
pt.ptmaxop1(a)
Maximum over particles
pt.max_all(a)
pt.ptmaxop_all1(a)
Maximum over all particles
pt.min(a)
pt.ptminop1(a)
Minimum over particles
pt.min_all(a)
pt.ptminop_all1(a)
Minimum over all particles
pt.max(a,b)
pt.ptmaxop1(a,b)
At maximum over particles
pt.max_all(a,b)
pt.ptmaxop_all1(a,b)
At maximum over all particles
pt.min(a,b)
pt.ptminop1(a,b)
At minimum over particles
pt.min_all(a,b)
pt.ptminop_all1(a,b)
At minimum over all particles