galpy.df.StreamTrack.from_particles

classmethod StreamTrack.from_particles(xv_particles, track_prog_cart, track_t_grid, arm_sign=1, ntp=None, ninterp=1001, smoothing=None, smoothing_factor=1.0, niter=0, order=2, velocity_weight='auto', prog_orbit=None, custom_sky_transform=None, ro=None, vo=None, zo=None, solarmotion=None)[source]

Build a StreamTrack by fitting a smooth curve to stream particles.

Runs the closest-point projection of each particle onto a finely-sampled progenitor orbit, bins the resulting offsets by progenitor time, smooths each coordinate (and optionally each covariance entry) through GCV or user-specified s, and reconstructs the dense track by adding the smoothed offsets back to the progenitor orbit. The tp parameter is interpreted as a galpy time, suitable for spraydf models.

After the fit, inst.particles holds the raw xv array the fit saw and inst.smoothing_s holds the effective per-spline s values (length 6 for order=1, 27 for order>=2) which can be passed back as smoothing in a subsequent call to reproduce the same smoothness without re-running GCV.

Parameters:

  • xv_particles (array, shape (6, N)) – Present-day phase space (R, vR, vT, z, vz, phi) of stream particles in galpy internal units.

  • track_prog_cart (array, shape (M, 6)) – Finely-sampled progenitor phase space (x, y, z, vx, vy, vz) at the times in track_t_grid. Must cover both sides of tp=0.

  • track_t_grid (array, shape (M,)) – The dense time grid on which track_prog_cart is evaluated.

  • arm_sign (int, optional) – +1 for leading arm (tp >= 0), -1 for trailing (tp <= 0).

  • ntp (int, optional) – Number of binning nodes. Default sqrt(N) with a floor of 21 and a ceiling that scales with the arc span (at least 201; larger for long streams).

  • ninterp (int, optional) – Resolution of the fine tp grid. Default 1001.

  • smoothing (None, float, or array-like, optional) – Smoothing parameter(s); see class docstring. None (default) uses GCV via make_smoothing_spline.

  • smoothing_factor (float, optional) – Multiplier applied to every spline’s effective s after GCV (or explicit-s) selection. Values > 1 force a smoother fit, values < 1 a rougher one. Useful when GCV undersmooths in finite samples (a common failure mode of make_smoothing_spline on noisy binned means). Default 1.0. For an interactive smoothing sweep, save track.particles from the first call and pass it back as particles= to subsequent streamspraydf.streamTrack calls — only the cheap re-fit step runs, the orbit-integration sample is reused.

  • niter (int, optional) – Iterations beyond the initial fit. Each iteration reassigns particles to the closest point on the current track.

  • order (int, optional) – 1 = mean only, 2 = mean + covariance.

  • velocity_weight (float or 'auto', optional) – Multiplicative weight applied to velocity components when computing 6D distances in the closest-point projection. Default 'auto' learns the weight from the inner-half particle dispersion (σ_pos / σ_vel, clipped to [0.1, 10]); see streamspraydf.streamTrack for motivation. Pass 1.0 for the legacy unweighted metric.

  • custom_sky_transform (array, shape (3, 3), optional) – Rotation from equatorial to a custom sky frame. Forwarded to the base __init__.

  • ro (float or Quantity, optional) – Distance scale (kpc). Default None — the resulting StreamTrack falls back onto the progenitor orbit’s ro value (and inherits its _roSet flag). Pass an explicit value only if the track should override the progenitor’s.

  • vo (float or Quantity, optional) – Velocity scale (km/s). Default None — same fallback to the progenitor as for ro.

  • zo (float or Quantity, optional) – Sun’s height above the midplane (kpc). Default None — falls back to the progenitor orbit’s zo.

  • solarmotion (str, numpy.ndarray or Quantity, optional) – 'hogg', 'dehnen', 'schoenrich', or [-U, V, W] in km/s. Default None — falls back to the progenitor’s.