11.21 sddsupsample

• description: sddsupsample provides for up-sampling of particle distributions from elegant.
• examples: Multiply the number of particles by 100 while preserving thin filaments
        sddsupsample input.sdds output.sdds \  
        --mode tangent --k 8 --alpha 0.01 --beta 0 --tan-cap-frac 0.02  
        --ortho-factor 0.5 --reject-factor 1.01 --max-tries 100  
      

• synposis:
  Usage:  
    sddsupsample in.sdds out.sdds --multiplier M [options]  
   
  Required:  
    --multiplier M        upsample factor (>1)  
   
  Options:  
    --mode MODE           tangent|interp (default tangent)  
    --k K                 kNN neighborhood (default 32)  
    --seed S              RNG seed (default 12345)  
   
  Tangent mode options:  
    --alpha A             ||dx_tan|| ~ A*r_k (default 0.02)  
    --beta B              ||dx_orth|| ~ B*sigma_o (default 0.0)  
    --tan-cap-frac F      cap ||dx_tan|| <= F*r_k (default 0.05; 0 disables)  
    --ortho-factor F      require ||dx_orth|| <= F*sigma_o (default 0.5; 0 disables)  
    --var-keep V          tangent variance fraction (default 0.99)  
    --reject-factor R     require ||dx|| <= R*r_k (default 1.01)  
    --max-tries T         attempts per new particle (default 50)  
   
  Interp mode options:  
    --noise S             Gaussian noise (whitened), default 0.02; 0 disables  
  

• Positional arguments:

  in.sdds

  Input SDDS file containing particle coordinates. Must include columns x, xp, y, yp, t, p.

  out.sdds

  Output SDDS file to write the upsampled particle set.

• Required arguments:

  –multiplier M (or -M)

  Upsampling factor. If the input has N particles, the output will have MN particles. Example: M = 100 turns 10⁵ particles into 10⁷ particles.

• Global options (apply to both modes):

  –mode {tangent|interp}

  Chooses how new particles are generated:

  • tangent: “jitter along the local filament/manifold” (best for preserving thin structures).
  • interp: “interpolate between nearby particles” (fills gaps; can smooth/blur filaments if overused).

  –k K

  Number of neighbors used to define “local.” Intuitively, this sets the size of the neighborhood from which local geometry is inferred.

  • Smaller K (8–16): more local, better at following tight curvature and keeping thin filaments thin, but can be noisier.
  • Larger K (32–64): smoother/more stable estimates, but more likely to mix nearby strands and blur fine structure.

  –seed S

  Random number seed for reproducibility. Same seed + same input + same options ⇒ same output.

• Tangent mode options (–mode tangent): Tangent mode tries to keep particles inside a thin “tube” around the original structure.

  –alpha A

  Controls how far you step along the local filament/manifold, relative to the local neighborhood scale. Larger A spreads points farther along the structure; too large can smear details or jump across features. Practical: start small (0.005–0.05).

  –beta B

  Controls how much you step across the filament (perpendicular thickness), relative to the measured local thickness.

  • B = 0: do not thicken filaments at all (safest for very thin structures).
  • Small B (0.05–0.2): allows slight “fuzz” if the real distribution has thickness.

  Too large will inflate/blur filaments.

  –tan-cap-frac F

  Hard cap on the along-filament step length, as a fraction of the neighborhood radius. Even if random draws would produce a large tangent move, this prevents big jumps that smear filaments. Smaller F preserves fine detail better (e.g. 0.01–0.05). Setting F = 0 disables the cap (not recommended for filamentary data).

  –ortho-factor F

  Hard cap on the perpendicular step, in units of the local perpendicular thickness. Think: “don’t let the new point leave the tube.” Smaller F is stricter. Setting F = 0 disables the perpendicular rejection test.

  –var-keep V

  Controls how many “tangent directions” are considered part of the filament/manifold. Local PCA finds directions of variation; V decides how many are treated as “along the structure.”

  • Higher V (0.99–0.999): more directions counted as tangent (can accidentally include thickness directions).
  • Lower V (0.95–0.99): fewer tangent directions (often safer for thin filaments).

  –reject-factor R

  Overall maximum step length, relative to the neighborhood radius. Smaller R keeps new points very close to their base particle; larger R allows more spread (and risk of smearing).

  –max-tries T

  How many times the code will resample a proposed step if it violates the caps/rejection tests. Larger T increases the chance of finding an acceptable point in very tight tubes, but costs runtime.

• Interp mode options (–mode interp): Interp mode makes new points by interpolating between a point and one of its neighbors.

  –noise S

  Adds small Gaussian jitter after interpolation (in normalized/whitened units).

  • S = 0: pure interpolation (points lie exactly on chords between neighbors).
  • Small S adds slight variation; too large blurs fine structures.

• Practical presets:

  Preserve extremely thin filaments

  --mode tangent --k 8 --alpha 0.01 --beta 0 --tan-cap-frac 0.02  
  --ortho-factor 0.5 --reject-factor 1.01 --max-tries 100

  Moderate filament thickness (allow slight cross-section)

  --mode tangent --k 16 --alpha 0.02 --beta 0.1 --tan-cap-frac 0.05  
  --ortho-factor 1.0 --reject-factor 1.02

  Fill gaps smoothly (less emphasis on thin filaments)

  --mode interp --k 32 --noise 0.01

• authors: GPT-Codex-5.2, M. Borland (ANL).