# Guitar fretting 05 — references and numerical safeguards

Context: `experimental/guitar-model-01/string_model.mjs` initializes a pluck
and changes modal frequencies along `pitchSteps`; it does not simulate fretting
contact or a pulling finger. `studies/guitar-articulation-04/README.md` correctly
calls that a pitch-path approximation and its alternative a picked diagnostic.
Neither establishes a physical hammer-on/pull-off or listening approval.

## Four primary sources

1. Gianpaolo Evangelista and Julius O. Smith III (2010),
   [Structurally Passive Scattering Element for Modeling Guitar Pluck Action](https://www.diva-portal.org/smash/get/diva2:535780/FULLTEXT01.pdf),
   DAFx-10, especially sections 3–5. Derives passive discrete finger/string
   couplings, including finger compliance, using the bilinear transform.
   Useful for contact impedance and driven release; this is a plucking model,
   not a complete fretting model, and assumes an ideally flexible string.

2. Stefan Bilbao and Alberto Torin (2014),
   [Numerical Simulation of String/Barrier Collisions: The Fretboard](https://www.pure.ed.ac.uk/ws/portalfiles/portal/17485791/dafx14_final.pdf),
   DAFx-14, sections 2.2–2.4, 3.3–3.5 and 5. Separates fretboard/fret collision
   from a compliant, damped stopping finger and accounts for player work.
   Includes tension modulation, contact interpolation and penetration checks.
   Its single polarization omits tangential fret friction; body coupling and
   gestural control are also not completed. Its scheme has its own stability
   condition, not a blanket guarantee for other discretizations.

3. Vasileios Chatziioannou and Maarten van Walstijn (2015),
   [Energy Conserving Schemes for the Simulation of Musical Instrument Contact Dynamics](https://arxiv.org/pdf/1501.01493),
   *Journal of Sound and Vibration* 339, 262–279,
   DOI `10.1016/j.jsv.2014.11.017`, sections 2.1–2.4, 3.3 and 5.
   Uses potential-energy differences to discretize unilateral contact. The
   comparisons explicitly show contact energy jumps with ordinary midpoint
   and trapezoidal rules. Finite precision, nonlinear-solver convergence and
   aliasing remain limitations even for the energy-conserving formulation.

4. David Südholt, Søren V. K. Lyster, Oliver B. Winkel and Stefania Serafin
   (2021), [A Real-Time Interactive Physical Model of the Langeleik Using Finite Difference Schemes and Web Audio](https://www.researchgate.net/publication/354632119_A_Real-Time_Interactive_Physical_Model_of_the_Langeleik_using_Finite_Difference_Schemes_and_Web_Audio),
   author-uploaded preprint, sections 2.3 and 4.1. Directly models a hammer-on
   through descending-finger collision, but approximates pull-off by resetting
   the finger state instantaneously. This is an adjacent fretted instrument,
   **not guitar validation**: the reset is a useful limitation to avoid, not a
   measured pulling gesture to copy.

## What the reduced model can claim

A bilateral spring/dashpot attached to a prescribed finger trajectory can
change the string's effective termination and transfer actuator work into an
already vibrating string. It can both push and pull, even without compression.
That is a compliant controlled termination, **not a complete fretboard
collision model**. Separate finger contact, actual fret/board geometry,
one-sided nonpenetration, separation and any tangential friction are needed
for the latter; even source 2 is explicitly limited to one polarization.

For this study, hammer-on should mean a descending finger contacting the
existing string; pull-off should mean a specified pulling/releasing gesture
while a lower stop or the nut remains. Merely opening a constraint transfers
existing energy but does not automatically model the lateral pull. Preserve
the full-string displacement and velocity through both events: no hidden new
pluck, frequency sweep or state reset. These are implementation requirements,
not a claim that the sources validate the eventual sound.

## Midpoint safeguards for the linear mass-string system

The following is an algebraic derivation for this study, not a replacement for
the nonlinear schemes in sources 2–3. Let `h > 0`, `v = q'`, and let a bar mean
the average of the two step endpoints. For constant symmetric `M > 0`,
`C >= 0`, `K >= 0`, discretize `M q'' + C q' + K q = F` together:

```text
q_next - q = h v_bar
M (v_next - v) = h (F_bar - C v_bar - K q_bar)
A = M + (h/2) C + (h*h/4) K
A v_bar = M v + (h/2) (F_bar - K q)
q_next = q + h v_bar;  v_next = 2 v_bar - v
E = (v^T M v + q^T K q)/2
E_next - E = h v_bar^T F_bar - h v_bar^T C v_bar
```

Solve the positive-definite system; do not form an inverse. Use matching
interpolation and transpose force distribution, consistent SI units and grid
mass weights, nonnegative spring/damping coefficients, and residual/finite
checks. The identity assumes a converged solve and unchanged matrices: moving
contacts, changed stiffness or deleted constraints require separate work or
energy accounting. Dropping loaded spring energy is not an invisible release.

For a fixed interpolation vector `b`, prescribed finger position `y`, and
bilateral coefficients `k_f, c_f >= 0`, use relative displacement
`e = b^T q - y` and relative velocity, including finger velocity. Assemble
`K = K0 + k_f b b^T`, `C = C0 + c_f b b^T`, and
`F_bar = F_ext_bar + b (k_f y_bar + c_f w)`, where
`w = (y_next - y)/h`. With the same endpoint averages throughout:

```text
relative_v = b^T v_bar - w
spring_force = k_f e_bar + c_f relative_v
E_total = (v^T M v + q^T K0 q + k_f e*e)/2
E_total_next - E_total = h v_bar^T F_ext_bar - h spring_force w
                         - h v_bar^T C0 v_bar - h c_f relative_v^2
```

The prescribed trajectory is an actuator port: increasing stored energy during
a hammer-on can be correct supplied work. Use continuous trajectories and
explicit engagement/release timing; account for changing `b` or `k_f` rather
than extending the fixed-contact identity to them. Prescribed motion does not
provide a dynamically reacting finger mass or measured hand biomechanics.

If adding unilateral contact, ordinary midpoint evaluation or force clipping
does not inherit this linear passivity result. Use an energy-consistent
potential difference/discrete gradient, its derivative limit near zero
increment, and verified nonlinear residuals as in source 3; test separation
and penetration explicitly.

## Bounded acceptance checks

- Verify lossless energy conservation and stationary-finger dissipative decay;
  for driven gestures check stored energy plus losses against signed actuator
  work, including engagement/release changes. Do not require monotone string
  energy while the finger is doing work.
- Check open and held-fret pitch, continuous state across hammer-on/pull-off,
  and a release with/without pulling displacement on the same vibrating string.
  Keep each string's mass/material calibration fixed across these comparisons.
- Refine timestep and string mesh separately; check pitch, attack spectrum,
  transient timing and contact penetration, not just bounded output. Midpoint
  warps an undamped mode to `omega_num = (2/h) atan(h*omega/2)`; stability does
  not establish bandwidth accuracy or prevent collision aliasing.
- Treat contact width, stiffness, damping and trajectories as declared study
  assumptions pending measurement. The old model's `contactWidthMeters` is a
  pluck-spectrum parameter, not measured finger anatomy. Energy/pitch tests
  establish numerical properties, **not realistic guitar tone or approval**;
  eventual assessment needs controlled dry-pickup and fixed-amp comparisons.