9.3
117 3D: Flow maps and volume change
procedure
(prepare-flow-map3d field seeds [ #:start-time start-time #:end-time end-time #:solver solver #:termination termination #:on-termination policy #:parallel? parallel? #:cancellation-token cancellation-token]) → prepared-flow-map3d? field : any/c seeds : seed-set3d? start-time : finite-real? = 0 end-time : finite-real? = 1 solver : any/c = #f termination : any/c = #f policy : (or/c 'absent 'use-termination-point) = 'absent parallel? : boolean? = #t cancellation-token : any/c = #f
Prepares
one retained trajectory in every declared seed slot. A normally completed slot
has its endpoint; an early-terminated slot is #f by default, or its
actual stopping point under 'use-termination-point. Thus source,
endpoint, and termination provenance stay aligned in seed order. Its diagnostics
contain a versioned preparation identity when field
is an ode-field3d with an explicit cache key and every termination
event has an explicit cache key. The identity records solver, seed-set,
termination, time-parameterization, dense-resampling, and endpoint policy.
An opaque field or event is reported as 'memory-only, so it is never
mistaken for persistently serializable numerical input. Independent seed slots
use bounded worker threads when #:parallel? is true; trajectories,
endpoints, diagnostics, and any raised failure retain seed order rather than
worker completion order.
procedure
(prepared-flow-map3d? value) → boolean?
value : any/c
Recognizes an immutable
prepared flow map. Its accessors begin with prepared-flow-map3d-.
procedure
(flow-map3d-ref map index) → (or/c false/c vec3?)
map : prepared-flow-map3d? index : exact-nonnegative-integer?
Returns the endpoint in seed order, or #f
for an absent endpoint.
procedure
(flow-map3d-pairs map) → vector?
map : prepared-flow-map3d?
procedure
(flow-map3d-displacement map index) → (or/c false/c vec3?)
map : prepared-flow-map3d? index : exact-nonnegative-integer?
Returns endpoint minus source for one slot.
procedure
(flow-map-grid3d map [ #:id id] #:connectivity connectivity) → group3d? map : prepared-flow-map3d? id : symbol? = 'flow-map-grid connectivity : 'axis-neighbours
Lowers
a flow map from an explicit 'grid seed set to retained endpoint edges.
An absent endpoint breaks its incident edges. Arbitrary unstructured seed sets
are rejected because no neighbourhood relation is implied by their order.
procedure
(flow-volume-cell3d map cell-index [ #:id id #:material material]) → mesh3d? map : prepared-flow-map3d? cell-index : exact-nonnegative-integer? id : (or/c false/c symbol?) = #f material : material3d? = default-material3d
Lowers
one retained hexahedral seed cell to its eight endpoint corners and twelve
outward-wound triangular faces. cell-index enumerates lower corners in
the source grid’s retained declaration order; it is not a loose seed index. The
operation requires an explicit complete grid and eight retained endpoints. It
does not interpolate, repair an absent endpoint, or infer volume from an
unstructured cloud.
procedure
(flow-map3d-local-jacobian map index) → linear3?
map : prepared-flow-map3d? index : exact-nonnegative-integer?
Estimates
the local endpoint derivative from a retained explicit grid neighbourhood.
Interior slots use central differences and grid boundaries use a retained
one-sided difference. An absent endpoint, incomplete axis neighbourhood, or
unstructured seed set is an error rather than a guessed result.
procedure
(flow-map3d-volume-factor map index) → finite-real?
map : prepared-flow-map3d? index : exact-nonnegative-integer?
Returns
the determinant of flow-map3d-local-jacobian at one grid slot.