List of JustPIC functions

Here an overview of all functions in JustPIC.jl, for a complete list see here:

JustPIC.AbstractAdvectionIntegrator Type

AbstractAdvectionIntegrator

Abstract supertype for time integrators used by particle, passive-marker, and marker-chain advection routines.

source

JustPIC.Euler Type

Euler()

Forward-Euler advection integrator.

This is the cheapest available integrator and is mainly useful for simple tests or when first-order accuracy is sufficient.

source

JustPIC.MarkerChain Type

MarkerChain{Backend,N,I,T1,T2,T3,TV} <: AbstractParticles

Container for a 2D marker chain used to represent a free surface or topographic interface as a single-valued height field y = h(x).

Markers are bucketed into the columns of a 1D grid (cell_vertices) using the same CellArray layout as Particles: each column holds up to max_xcell marker slots, and a boolean occupancy mask marks which are live.

Fields

• coords::NTuple{N,T1}: marker coordinates, one CellArray per dimension. In 2D coords[1] is x and coords[2] is y. Empty slots hold NaN.

• coords0::NTuple{N,T1}: marker coordinates from the previous time step.

• h_vertices::T2: topography sampled at the grid vertices (current step).

• h_vertices0::T2: topography at the vertices from the previous step; used by advect_markerchain!/semilagrangian_advection_markerchain! to conserve the mean height.

• cell_vertices::TV: the horizontal grid xv that defines the columns. It must be finite and strictly increasing; the spacing may be non-uniform, in which case every operation resolves each column's width from its own pair of vertices.

• index::T3: per-slot occupancy mask (true ⟺ the matching coords slot is live).

• min_xcell, max_xcell::I: the minimum and maximum number of markers allowed per column; resample! refills depleted columns back up to min_xcell.

Invariants

• A slot is live iff its mask entry is true; live slots have finite coordinates and empty slots are NaN.

• Marker precision follows eltype(cell_vertices)/the initial elevation, so a Float32 grid yields Float32 markers (needed on Metal, which has no Float64).

Use init_markerchain to create a chain, fill_chain_from_chain! or fill_chain_from_vertices! to overwrite its geometry, and advect_markerchain! or semilagrangian_advection_markerchain! to evolve it in time.

source

JustPIC.Particles Type

Particles{Backend, N, I, T1, T2, D, V} <: AbstractParticles

Main particle container used by JustPIC for material points stored cell-by-cell in CellArrays.

coords is an N-tuple of particle-coordinate arrays, index marks which slots are active inside each cell, nxcell is the target initial occupancy per cell, and min_xcell/max_xcell define the occupancy range used by injection and cleanup routines.

Use init_particles to construct this type instead of calling the inner constructor directly.

source

JustPIC.PassiveMarkers Type

PassiveMarkers{Backend,T} <: AbstractParticles

Lightweight particle container for passive tracers that only store coordinates.

Unlike Particles, passive markers do not keep per-cell occupancy metadata and are intended for tracer-style advection and interpolation workflows where the markers do not feed back into the simulation.

Use init_passive_markers to construct this type.

source

JustPIC.PhaseRatios Type

PhaseRatios{Backend,T}

Storage for phase-fraction fields sampled at multiple grid locations.

Depending on dimension, the container holds phase ratios at cell centers, vertices, staggered velocity nodes, and in 3D also at edge midpoints.

The fields store, for each location, the fractional occupancy of each material phase inferred from particle labels.

source

JustPIC.PhaseRatios Method

PhaseRatios(T, backend, nphases, ni)
PhaseRatios(backend, nphases, ni)
PhaseRatios(nphases, ni)

Allocate a PhaseRatios container for nphases material phases on a grid of size ni.

The default element type is Float64 and the default backend is KernelAbstractions' CPU.

Arguments

• T: scalar storage type for the phase fractions.

• backend: backend type used to allocate the arrays.

• nphases: number of material phases.

• ni: number of cells in each spatial direction.

source

JustPIC.RungeKutta2 Type

RungeKutta2(α = 0.5)

Second-order Runge-Kutta advection integrator.

The parameter α controls the intermediate stage location and must satisfy 0 < α < 1. The default α = 0.5 corresponds to the midpoint method.

source

JustPIC.RungeKutta4 Type

RungeKutta4()

Classical fourth-order Runge-Kutta advection integrator.

source

JustPIC.SubgridDiffusionCellArrays Type

SubgridDiffusionCellArrays(particles; loc = :vertex)

Allocate scratch storage used by the subgrid thermal diffusion routines.

The returned object stores old particle temperatures, per-particle temperature increments, characteristic diffusion timescales, and a grid-sized accumulation buffer.

loc selects whether the accumulation buffer should match a vertex-based (:vertex) or cell-centered (:center) grid layout. Either way the buffer is ghosted like particles.xvi/particles.xci.

source

JustPIC.CA Method

CA(backend, dims; eltype = Float64)

Allocate an uninitialized CellArray of size dims on backend. Extended for the GPU backends by the package extensions.

source

JustPIC.TA Method

TA()
TA(backend)

Return the plain array type associated with backend (a KernelAbstractions backend type such as CPU).

For CPU this is Array. Loading CUDA.jl / AMDGPU.jl / Metal.jl extends this for CUDA.CUDABackend, AMDGPU.ROCBackend, and Metal.MetalBackend, respectively.

source

JustPIC.add_periodic_ghost_nodes Method

add_periodic_ghost_nodes(x::AbstractVector)

Extend a 1D periodic grid with one ghost node on each side.

The added coordinates preserve the spacing of the last and first physical cells, respectively, which makes this helper work for both uniform and refined grids.

Example

xv = [0.0, 0.25, 0.5, 0.75, 1.0]
xv_periodic = add_periodic_ghost_nodes(xv)

source

JustPIC.advect_markerchain! Method

advect_markerchain!(chain, method, V, grid_vxi, dt)

Advect a marker chain for one time step and rebuild its derived topography data.

This convenience wrapper runs marker advection, reassigns markers to cells, resamples the chain, updates vertex elevations, and enforces mean-height conservation.

Use this when evolving a free surface or interface represented by a MarkerChain.

source

JustPIC.advection! Method

advection!(particles::Particles, method::AbstractAdvectionIntegrator, V, dt)
advection!(particles::Particles, method::AbstractAdvectionIntegrator, V, grid_vi, dt, dxi)

Advect particles through the staggered velocity field V over a time step dt. The particle coordinates are updated in place.

The public form reads the staggered velocity coordinate grids and spacing from particles (particles.xi_vel and particles.di.velocity), so only V and dt are supplied. The lower-level form takes those grids explicitly.

Arguments

• particles: Particles container to advect.

• method: time integrator such as Euler(), RungeKutta2(), or RungeKutta4().

• V: tuple of staggered velocity component arrays.

• dt: timestep.

• grid_vi: tuple of coordinate tuples matching the staggering of V (lower-level form only).

• dxi: grid spacing associated with grid_vi (lower-level form only).

• periodic_1, periodic_2, periodic_3: enable periodic wrapping at every integration stage in the corresponding coordinate direction.

Notes

• Use the same periodic keywords in the subsequent move_particles! call.

• Stage-wise wrapping is required by RungeKutta2 and RungeKutta4, whose intermediate interpolation points may cross a periodic boundary.

source

JustPIC.advection! Method

advection!(particles::PassiveMarkers, method::AbstractAdvectionIntegrator, V, grid_vxi, dt)

Advect passive marker coordinates through the staggered velocity field V over a time step dt. The marker coordinates are updated in place.

Unlike the Particles method, grid_vxi must be supplied explicitly, since PassiveMarkers stores only marker coordinates and no grid metadata.

Arguments

• particles: PassiveMarkers container to advect.

• method: time integrator such as Euler(), RungeKutta2(), or RungeKutta4().

• V: tuple of staggered velocity component arrays.

• grid_vxi: tuple of coordinate tuples matching the staggering of V.

• dt: timestep.

source

JustPIC.advection! Method

advection!(chain::MarkerChain, method, V, grid_vi, dt)

Advect the marker coordinates in chain through the staggered velocity field V without performing resampling or topography reconstruction.

This lower-level method is useful if you want to customize the post-advection marker-chain processing yourself.

source

JustPIC.advection_LinP! Method

advection_LinP!(particles, method, V, dt; periodic_1=false, periodic_2=false, periodic_3=false)

Advect particles using the linear-plus-pressure (LinP) velocity interpolation scheme.

This variant uses the same time integrators as advection! but evaluates velocities with the LinP reconstruction near staggered pressure points.

This method is useful when you want the interpolation behavior described in the velocity-interpolation documentation under LinP.

Periodic keywords have the same meaning as in advection! and must also be passed to the subsequent move_particles! call.

source

JustPIC.advection_MQS! Method

advection_MQS!(particles, method, V, dt; periodic_1=false, periodic_2=false, periodic_3=false)

Advect particles using the monotonic quadratic spline (MQS) velocity interpolation scheme.

Compared with advection!, this method reconstructs staggered velocities with MQS where enough stencil support is available.

Near boundaries or when the required stencil is unavailable, the implementation falls back to linear interpolation.

The public entry point reads the staggered velocity coordinates and spacing from particles.xi_vel and particles.di.velocity.

Periodic keywords have the same meaning as in advection! and must also be passed to the subsequent move_particles! call.

source

JustPIC.cell_array Method

cell_array(backend, x, ncells::NTuple, ni::NTuple)
cell_array(x, ncells::NTuple, ni::NTuple)

Allocate a CellArray on backend (a KernelAbstractions backend type such as CPU), with ncells entries per grid cell over a grid of size ni, and fill every entry with x.

The backend form is the preferred allocation path for particle storage and phase-ratio arrays. The backend-less form allocates on CPU.

Examples

index = cell_array(CPU, false, (24,), (64, 64))
field = cell_array(CPU, 0.0, (3,), (64, 64))

source

JustPIC.cell_length Method

cell_length(chain::MarkerChain, i::Integer)
cell_length(chain::MarkerChain)

Return the horizontal width of column i of a 2D marker chain, that is chain.cell_vertices[i + 1] - chain.cell_vertices[i].

The one-argument method returns the width shared by every column, and is therefore defined only when chain.cell_vertices is uniformly spaced; on a refined grid it throws an ArgumentError.

source

JustPIC.cell_rock_area Method

cell_rock_area(s::Segment, r::Rectangle) -> Real

Fraction of the axis-aligned cell r lying below the marker chain segment s, in [0, 1].

s spans the full width of r, runs left to right, and may leave the cell through its floor or its ceiling.

source

JustPIC.cell_width Method

cell_width(xv, i)

Width of cell i of the vertex vector xv.

source

JustPIC.cellaxes Method

cellaxes(A)

Return the one-based axes used to iterate over the entries inside each CellArray cell.

This is the preferred helper for loops over particle slots because it works for both scalar and multi-entry cell storage.

source

JustPIC.cellnum Method

cellnum(A::CellArray)

Return the number of storage slots inside each logical cell of A.

For particle containers this is the number of particle slots reserved per grid cell, including inactive slots.

source

JustPIC.centroid2particle! Method

centroid2particle!(Fp, xci, F, particles)

Interpolate cell-centered field values F to particle values Fp.

xci contains the center coordinates of the grid carrying F. The destination Fp is mutated in place and may be either a single particle field or a tuple of particle fields.

Particles lying between a domain boundary and the first centroid are interpolated from the ghost centroids, so F must always use the ghosted particles.xci layout — unlike grid2particle!, there is no opt-out.

source

JustPIC.checkpointing_particles Method

checkpointing_particles(dst, particles; phases=nothing, phase_ratios=nothing, chain=nothing, t=nothing, dt=nothing, particle_args=nothing)
checkpointing_particles(dst, particles, me; phases=nothing, phase_ratios=nothing, chain=nothing, t=nothing, dt=nothing, particle_args=nothing)

Write particle state and optional companion data to a JLD2 checkpoint.

By default the file is saved as particles_checkpoint.jld2 in dst. Additional keyword arguments are serialized into the checkpoint after being converted to plain Julia arrays where needed.

Common keywords

• phases: per-particle phase labels.

• phase_ratios: PhaseRatios container to checkpoint.

• chain: marker-chain state.

• t: simulation time.

• dt: timestep size.

• particle_args: tuple of extra particle-carried fields.

Notes

• Arrays are converted to plain Julia arrays before serialization so the checkpoint can be reloaded independently of the active backend.

• Passing me writes rank-local files named after the zero-based MPI rank: particles_checkpoint0000.jld2, particles_checkpoint0001.jld2, and so on.

source

JustPIC.clean_particles! Method

clean_particles!(particles, grid, args)

Remove invalid or inactive particle slots and keep particle-associated fields in args consistent with the particle storage layout.

This is typically used after particle deletion or reinjection to compact each cell's active particle block.

source

JustPIC.compute_rock_fraction! Method

compute_rock_fraction!(ratios, chain::MarkerChain, xvi, dxi)

Fill ratios with the fraction of each control volume that lies below the marker chain.

The result is written at cell centers, vertices, and staggered velocity nodes using the topography currently stored in chain.

xvi are the cell vertices per direction and dxi the matching spacings: either one Number per direction for a uniform grid, or one AbstractVector of per-cell widths per direction for a refined one.

source

JustPIC.compute_topography_vertex! Method

compute_topography_vertex!(chain::MarkerChain)

Interpolate the marker-chain geometry back to the vertex-based topography array chain.h_vertices.

This is typically called after marker advection or resampling.

source

JustPIC.fill_chain_from_chain! Method

fill_chain_from_chain!(chain::MarkerChain, topo_x, topo_y)

Replace the marker positions in chain with coordinates sampled from an existing topographic polyline.

After the markers are reassigned, the vertex-based topography stored on the chain is recomputed and synchronized with h_vertices0.

topo_x and topo_y should describe an open polyline that spans the chain's horizontal extent.

source

JustPIC.fill_chain_from_vertices! Method

fill_chain_from_vertices!(chain::MarkerChain, topo_y)

Reconstruct a marker chain from topography values given at grid vertices.

topo_y is copied into both the current and previous vertex topography fields before the marker coordinates are rebuilt.

This is useful when the interface is naturally represented on the vertex grid and you want to refresh the marker representation from that discretization.

source

JustPIC.find_parent_cell_bisection Method

find_parent_cell_bisection(px::Number, x::AbstractVector, seed::Int)

Performs an iterative bisection search on the cell-edge vector x to find the index of the cell containing px, starting from the initial guess seed.

Arguments

• px::Number: Coordinate of the point we want to locate.

• x::AbstractVector: Monotonic vector of cell-edge coordinates.

• seed::Int: Initial cell index guess used to start the search.

Returns

• An integer index i such that x[i] ≤ px ≤ x[i + 1].

source

JustPIC.force_injection! Method

force_injection!(particles, p_new)

Convenience method for force_injection! when no companion particle fields need to be initialized.

source

JustPIC.force_injection! Method

force_injection!(particles, p_new, fields, values)

Insert particles from p_new directly into free particle slots.

Arguments

• particles: destination Particles container.

• p_new: per-cell collection of coordinates to inject; NaN marks empty input slots.

• fields: tuple of particle fields to initialize together with the coordinates.

• values: values written into each corresponding entry of fields.

Notes

• This is a low-level routine: it does not search for nearest-neighbor values.

• Injection only happens into currently inactive particle slots.

source

JustPIC.grid2particle! Method

grid2particle!(Fp, xvi, F, particles::PassiveMarkers)

Interpolate a nodal field F to passive-marker values Fp, updated in place.

The vertex grid xvi must be supplied explicitly, since PassiveMarkers stores only marker coordinates and no grid metadata.

Arguments

• Fp: destination marker field, or tuple of marker fields.

• xvi: vertex coordinates of the grid on which F is defined.

• F: source nodal field, or tuple of nodal fields matching Fp.

• particles: PassiveMarkers container supplying marker coordinates.

source

JustPIC.grid2particle_flip! Method

grid2particle_flip!(Fp, xvi, F, F0, particles; α = 0.0)

Update particle values with a PIC/FLIP blend.

α = 1 gives pure PIC, α = 0 gives pure FLIP, and intermediate values blend between the two updates.

Arguments

• Fp: particle field to update in place.

• F: current grid field.

• F0: previous grid field.

• particles: particle container.

• α: PIC fraction in the PIC/FLIP blend.

• ghost_1, ghost_2, ghost_3: whether F and F0 include ghost nodes in each coordinate direction. Disable a keyword for a physical-only direction.

source

JustPIC.init_cell_arrays Method

init_cell_arrays(particles::Particles, ::Val{N})

Allocate N cell-aligned scratch arrays with the same cell layout as particles.coords.

This is mainly used internally to create per-particle temporary storage for quantities such as interpolated fields or time-integration work arrays.

Returns

• An N-tuple of CellArrays with the same particle-cell layout as particles.coords.

source

JustPIC.init_markerchain Method

init_markerchain(backend, nxcell, min_xcell, max_xcell, xv, initial_elevation)

Create a 2D MarkerChain sampled along the horizontal grid xv.

The vertices in xv must be finite and strictly increasing; the spacing may be non-uniform, in which case each column is populated according to its own width.

nxcell controls the initial number of markers per cell, while initial_elevation can be either a scalar or a vector specifying the initial surface height.

Returns

• A MarkerChain whose marker positions, vertex topography, and occupancy masks are initialized consistently.

source

JustPIC.init_particles Method

init_particles(backend, nxcell, max_xcell, min_xcell, grid_vx, grid_vy[, grid_vz])

Initialize a Particles container from the staggered velocity grids.

Each velocity component is supplied as an N-tuple of coordinate vectors. The diagonal coordinate vector of each component defines the particle vertex grid; the off-diagonal vectors define the cell-center grid. For example, in 2D pass grid_vx = (xv, yc_extended) and grid_vy = (xc_extended, yv).

If nxcell is a number, particles are distributed randomly within cell quadrants. If it is an NTuple, it is interpreted as the number of particles to place regularly along each coordinate direction within every cell.

The particle vertex and center grids stored in the returned container are extended with periodic ghost nodes. The staggered velocity grids are stored as provided.

Arguments

• backend: KernelAbstractions backend type such as CPU.

• nxcell: either the target number of particles per cell, or an NTuple describing a structured per-dimension layout.

• max_xcell: number of particle slots reserved per cell.

• min_xcell: minimum occupancy used by reinjection routines.

• grid_vx, grid_vy, grid_vz: staggered velocity-grid coordinate tuples. Omit grid_vz for a 2D simulation. Each tuple must contain one coordinate vector per spatial dimension.

Returns

• A Particles object whose coordinates and occupancy arrays are ready for advection/interpolation routines, with particles.xvi and particles.xci including one periodic ghost node on each side.

Example

xv, yv = LinRange(0, 1, 33), LinRange(0, 1, 33)
dx = xv[2] - xv[1]
xc = LinRange(dx / 2, 1 - dx / 2, 32)
yc = xc
grid_vx = xv, LinRange(first(yc) - dx, last(yc) + dx, 34)
grid_vy = LinRange(first(xc) - dx, last(xc) + dx, 34), yv
particles = init_particles(CPU, 24, 48, 12, grid_vx, grid_vy)

source

JustPIC.init_passive_markers Method

init_passive_markers(backend, coords::NTuple{N,AbstractArray})

Construct a PassiveMarkers container on backend from marker coordinate arrays.

coords is an N-tuple of vectors, one per spatial dimension, holding the initial marker positions: marker k sits at (coords[1][k], …, coords[N][k]).

Arguments

• backend: KernelAbstractions backend type such as CPU.

• coords: tuple of coordinate vectors, one per dimension.

source

JustPIC.inject_particles! Method

inject_particles!(particles::Particles, args)

Inject particles into cells whose occupancy falls below particles.min_xcell.

Arguments

• particles: The particles object.

• args: tuple of particle fields that should be populated for newly injected particles.

Notes

• New particles are placed quadrant-by-quadrant inside the cell.

• New field values are copied from the nearest existing particle in the same neighborhood.

• The public entry point uses the vertex grid and cell spacing stored in particles.

source

JustPIC.inject_particles_phase! Method

inject_particles_phase!(particles, particles_phases, args, fields, grid)

Inject particles into under-populated cells while also copying phase labels and field values from nearby particles.

This is the phase-aware variant of inject_particles!.

particles_phases stores a phase id per particle slot, while args/fields hold companion particle properties that must be initialized consistently for the new particles.

source

JustPIC.interpolate_velocity_to_markerchain! Method

interpolate_velocity_to_markerchain!(chain::MarkerChain, chain_V::NTuple{N, CellArray}, V, grid_vi::NTuple{N, NTuple{N, T}}) where {N, T}

Interpolate the staggered velocity field V to the current marker positions in chain and store the result in chain_V.

chain_V must be preallocated with the same cell layout as the marker-chain coordinates.

source

JustPIC.launch! Method

launch!(backend, kernel!, ndrange, args...)

Instantiate and run KernelAbstractions kernel! on backend over ndrange, then block until it completes.

The trailing synchronize keeps the package's historical synchronous launch semantics: host reads, MPI halo exchanges and injection/cleanup all assume the previous kernel has finished. A later optimization pass may drop per-launch synchronization in favor of synchronizing only before host access.

source

JustPIC.lerp Method

lerp(v, t::NTuple{nD,T}) where {nD,T}

Linearly interpolates the value v between the elements of the tuple t. This function is specialized for tuples of length nD.

Arguments

• v: The value to be interpolated.

• t: The tuple of values to interpolate between.

source

JustPIC.mean_height Method

mean_height(chain::MarkerChain)

Return the domain mean of the piecewise-linear vertex topography.

source

JustPIC.move_particles! Method

move_particles!(particles::AbstractParticles, args; periodic_1=false, periodic_2=false, periodic_3=false)
move_particles!(particles::AbstractParticles, grid, args, dxi; periodic_1=false, periodic_2=false, periodic_3=false)

Reassign particles to the correct parent cells after their coordinates have been updated.

This routine keeps the coordinate arrays in particles and the companion fields in args sorted by parent cell, preserving the package's spatially local memory layout.

Arguments

• particles: particle container whose coordinates have already been modified.

• args: tuple of per-particle fields that must move together with the particle coordinates.

• grid: optional vertex grid coordinates used by the lower-level method.

• dxi: optional grid spacing used by the lower-level method.

• periodic_1, periodic_2, periodic_3: enable periodic wrapping in the corresponding coordinate direction.

Notes

• Particles that leave a non-periodic direction are discarded.

• Periodic directions use the ghost cells created by add_periodic_ghost_nodes to wrap coordinates and particle fields across opposite domain boundaries.

• args must use the same cell layout as particles.coords.

• The public entry point uses the vertex grid and spacing stored in particles.

source

JustPIC.move_particles! Method

move_particles!(chain::MarkerChain)

Reassign markers to the correct columns of chain after their coordinates have been updated.

Markers that crossed column boundaries are moved into their destination column's slots, keeping the coordinate arrays consistent with the per-column occupancy mask. A marker may cross any number of columns in one call. Markers whose updated coordinates are not finite, or which left the horizontal extent of chain.cell_vertices, are deleted.

source

JustPIC.new_empty_cell Method

new_empty_cell(A::CellArray)

Create a zero-valued cell payload with the same element type as A.

source

JustPIC.nphases Method

nphases(x::PhaseRatios)

Return the number of phases in x::PhaseRatios.

This method returns a Val wrapper for the phase count; use numphases when you need the integer directly.

source

JustPIC.parent_cell_index Method

parent_cell_index(x, xv, seed)

Return the index i of the cell of the vertex vector xv that contains x, i.e. the i such that xv[i] ≤ x < xv[i + 1], clamped to 1:length(xv) - 1.

xv may be uniformly spaced (an AbstractRange, resolved arithmetically) or refined (any other AbstractVector, resolved by bisection from the initial guess seed). seed is ignored in the uniform case.

source

JustPIC.particle2centroid! Method

particle2centroid!(F, Fp, particles::Particles)
particle2centroid!(F, Fp, xci::NTuple, particles::Particles, di)

Interpolate particle-centered values Fp to cell centers F.

xci contains the 1D coordinate arrays of the cell centers. This is the cell-centered counterpart to particle2grid! and mutates F in place.

Arguments

• F: destination centroid array, or tuple of centroid arrays.

• Fp: particle field stored with the same cell layout as particles.

• particles: the Particles container supplying particle coordinates. Its stored xci coordinates define the target centroid grid.

• ghost_1, ghost_2, ghost_3: whether F includes ghost nodes in each coordinate direction. Disable a keyword for a physical-only direction.

source

JustPIC.particle2grid! Method

particle2grid!(F, Fp, buffer, xi, particles::PassiveMarkers)

Interpolate passive-marker values Fp onto the grid nodes F, overwriting F in place.

Because passive markers scatter to arbitrary nodes, weights are accumulated with atomic updates into F and buffer and normalized in a final pass; buffer must be a scratch array with the same size as F. The vertex grid xi is supplied explicitly.

Arguments

• F: destination nodal array.

• Fp: marker field stored with the same layout as particles.coords.

• buffer: scratch nodal array (same size as F) used to accumulate weights.

• xi: vertex coordinates of the target grid.

• particles: PassiveMarkers container supplying marker coordinates.

source

JustPIC.reconstruct_chain_from_vertices! Method

reconstruct_chain_from_vertices!(chain::MarkerChain)

Rebuild the markers of each column by evenly distributing them along the straight segment joining the two bounding h_vertices.

The number of markers per column is preserved (empty slots are skipped, so the column need not be contiguously packed). This is the inverse of compute_topography_vertex! and is used after the vertex topography has been modified (e.g. by the mass-conservation step of advect_markerchain! or the slope limiting of semilagrangian_advection_markerchain!).

source

JustPIC.resample! Method

resample!(chain::MarkerChain)

Resample the markers within each chain cell when the chain becomes too sparse or too distorted.

This keeps the marker spacing reasonably regular, which improves interpolation quality and the stability of subsequent marker-chain operations.

source

JustPIC.semilagrangian_advection! Method

semilagrangian_advection!(F, F0, method, V, grid_vi, grid, dt)

Advect a grid field with a semi-Lagrangian backtracking step.

Each destination node in F is traced backward through the velocity field V, then sampled from F0 on the vertex grid grid. grid_vi contains the staggered coordinates associated with the velocity components.

Notes

• F is overwritten in place.

• F0 is the source field from the previous step.

• For tuple-valued fields, each component is backtracked independently.

source

JustPIC.semilagrangian_advection! Method

semilagrangian_advection!(chain::MarkerChain, method, V, grid_vxi, grid, dt)

Advance only the vertex topography chain.h_vertices by one semi-Lagrangian step.

Each vertex height is updated by backtracking its position through the velocity field V (so method must support backtracking, i.e. RungeKutta2/RungeKutta4, not Euler). This is the raw update used by semilagrangian_advection_markerchain!; it does not apply slope limiting, mass conservation, or marker reconstruction — call the wrapper unless you need to compose those steps yourself.

source

JustPIC.semilagrangian_advection_LinP! Method

semilagrangian_advection_LinP!(F, F0, method, V, grid_vi, grid, dt)

Semi-Lagrangian advection variant that evaluates backtracked velocities with the LinP interpolation scheme.

Use this when the advecting velocity should be reconstructed with the LinP scheme instead of plain linear interpolation.

source

JustPIC.semilagrangian_advection_MQS! Method

semilagrangian_advection_MQS!(F, F0, method, V, grid_vi, grid, dt)

Semi-Lagrangian advection variant that evaluates backtracked velocities with the MQS interpolation scheme.

Use this when the advecting velocity should be reconstructed with the MQS scheme instead of plain linear interpolation.

source

JustPIC.semilagrangian_advection_markerchain! Method

semilagrangian_advection_markerchain!(chain, method, V, grid_vxi, grid, dt; max_slope_angle = 45.0)

Backtrack a marker chain through V and update the chain geometry with a semi-Lagrangian step.

Unlike advect_markerchain!, which moves the Lagrangian markers, this scheme updates the vertex topography directly by backtracking each vertex (via the lower-level semilagrangian_advection!), then limits the local slope to max_slope_angle degrees (via smooth_slopes!), restores the mean height for mass conservation, and finally rebuilds the markers from the updated vertices. It is well suited to steep or strongly sheared surfaces where marker advection would tangle.

method must support backtracking (RungeKutta2 or RungeKutta4; Euler is not supported). grid_vxi holds the staggered velocity grids and grid the chain's vertex grid.

source

JustPIC.set_precision Method

set_precision(integrator, T)

Recast an integrator's stored parameters to the scalar precision T.

This is applied at the advection launch sites so that a Float32 backend (such as Metal, which has no Float64) never carries a Float64 field into a GPU kernel. It is the identity for parameter-free integrators and, on the Float64 CPU/CUDA/AMDGPU path, a no-op (the value is preserved).

source

JustPIC.smooth_slopes! Method

smooth_slopes!(chain::MarkerChain, max_angle::Real)

Limit the local slope of the vertex topography to max_angle (in radians).

Interior vertices whose left or right slope steeper than tan(max_angle) are replaced by a 3-point average of themselves and their neighbours (LaMEM-style limiting). This suppresses the spurious spikes that semi-Lagrangian backtracking can introduce on a steep interface; it is applied automatically inside semilagrangian_advection_markerchain!. Chains with fewer than three vertices are left untouched.

source

JustPIC.subgrid_diffusion! Method

subgrid_diffusion!(pT, T_grid, ΔT_grid, subgrid_arrays, particles, dt; d = 1.0)

Apply the vertex-based subgrid diffusion correction to particle temperatures.

Temperatures are interpolated from the grid to particles, relaxed using the local subgrid model, mapped back to the grid as a correction, and then reapplied to the particle temperatures.

Arguments

• pT: particle temperature field updated in place.

• T_grid: source temperature on the ghosted vertex grid, sized as length.(particles.xvi).

• ΔT_grid: resolved-grid temperature increment carrying one ghost node per side, sized ncells .+ 2.

• subgrid_arrays: scratch storage created with SubgridDiffusionCellArrays(particles).

• particles: particle container.

• dt: timestep.

• d: dimensionless subgrid diffusion coefficient.

source

JustPIC.subgrid_diffusion_centroid! Method

subgrid_diffusion_centroid!(pT, T_grid, ΔT_grid, subgrid_arrays, particles, dt; d = 1.0)

Centroid-grid variant of subgrid_diffusion!.

Use this when the resolved temperature field lives at cell centers instead of vertices. T_grid is then the ghosted centroid field sized as length.(particles.xci), while ΔT_grid keeps the same ncells .+ 2 layout as in subgrid_diffusion!.

source

JustPIC.update_cell_halo! Method

update_cell_halo!(x::CellArray...)

Synchronize the overlapping MPI halo of one or more CellArrays in place.

This is the CellArray companion to ImplicitGlobalGrid.update_halo! and is typically used after particle coordinates or per-particle fields have changed on each rank.

Arguments

• x: one or more CellArrays with the same logical grid layout.

Notes

• Every provided CellArray is updated; this is convenient for particles.coords, particles.index, and particle field arrays returned by init_cell_arrays.

• For MPI particle advection, halo exchange is usually required before move_particles! so that particles that crossed a rank boundary are visible to the neighboring rank.

• With periodic boundary conditions, update_cell_halo! exchanges the overlap across the periodic domain boundaries as configured in init_global_grid.

• If particles are reinjected with inject_particles!, refresh the halos again before reconstructing grid fields with particle2grid!.

Example

advection!(particles, RungeKutta2(), V, dt)
update_cell_halo!(particles.coords...)
update_cell_halo!(particle_args...)
update_cell_halo!(particles.index)
move_particles!(particles, particle_args)
inject_particles!(particles, particle_args)
particle2grid!(T, pT, particles)

source

JustPIC.@idx Macro

@idx(args...)

Make a linear range from 1 to args[i], with i ∈ [1, ..., n]

source