{"id":1923,"date":"2026-10-18T13:26:16","date_gmt":"2026-10-18T17:26:16","guid":{"rendered":"https:\/\/web.uri.edu\/nld\/ncvd-toolbox\/"},"modified":"2026-10-21T20:00:31","modified_gmt":"2026-10-22T00:00:31","slug":"ncvd-toolbox","status":"publish","type":"page","link":"https:\/\/web.uri.edu\/nld\/ncvd-toolbox\/","title":{"rendered":"NCVD toolbox"},"content":{"rendered":"\n
\n

<\/span>Nonlinear Dynamics Laboratory<\/p>\n

NCVD toolbox<\/h1><\/div>\n\"\"\n<\/div>\n\n\n\n
\"Animation:
One free decay of a three-mass chain with a cubic spring. Each shaded window is decomposed; the three resonances trace their frequency-energy dependence back to the linear frequencies.<\/figcaption><\/figure>\n\n\n\n

Nonlinear Characteristic Value Decomposition: modal identification from a measured or simulated state record, with exact identities, pole correction for numerical derivatives, noise-robust operators, measured forcing, ensembles of records, and amplitude-dependent identification of nonlinear structures. MATLAB and Python, MIT license.<\/p>\n\n\n\n

Code on GitHub<\/a>User manual (PDF)<\/a>Live slides<\/a>Slides (PDF)<\/a>Slides (PowerPoint)<\/a>doi:10.5281\/zenodo.23549069<\/a><\/p>\n\n\n\n

<\/span>The decomposition<\/p>\n\n\n\n

One state record, two identities, both exact<\/h2>\n\n\n\n

With displacement, velocity and acceleration at n<\/mi><\/mrow>n<\/annotation><\/semantics><\/math> stations, the toolbox writes the state record and its rate as<\/p>\n\n\n\n𝐗<\/mi>1<\/mn><\/msub>=<\/mo>[<\/mo>𝐪<\/mi>,<\/mo> <\/mtext>𝐪<\/mi><\/mrow>˙<\/mo><\/mover>]<\/mo>=<\/mo>𝐔<\/mi>\ud835\udebd<\/mi><\/mrow>𝖧<\/mi><\/mrow><\/msup>,<\/mo>𝐗<\/mi>2<\/mn><\/msub>=<\/mo>[<\/mo>𝐪<\/mi><\/mrow>˙<\/mo><\/mover>,<\/mo> <\/mtext>𝐪<\/mi><\/mrow>¨<\/mo><\/mover>]<\/mo>=<\/mo>𝐔<\/mi>\ud835\udeb2<\/mi><\/mrow>\ud835\udebd<\/mi><\/mrow>𝖧<\/mi><\/mrow><\/msup>+<\/mo>𝐑<\/mi><\/mrow>\\mathbf{X}_1=[\\mathbf{q},\\ \\dot{\\mathbf{q}}]=\\mathbf{U}\\boldsymbol{\\Phi}^{\\mathsf{H}},\\qquad \\mathbf{X}_2=[\\dot{\\mathbf{q}},\\ \\ddot{\\mathbf{q}}]=\\mathbf{U}\\boldsymbol{\\Lambda}\\boldsymbol{\\Phi}^{\\mathsf{H}}+\\mathbf{R}<\/annotation><\/semantics><\/math>\n\n\n\n

where \ud835\udc14<\/mi><\/mrow>\\mathbf{U}<\/annotation><\/semantics><\/math> is the temporal basis, \ud835\udebd<\/mi><\/mrow><\/mrow>\\boldsymbol{\\Phi}<\/annotation><\/semantics><\/math> the characteristic shapes, \ud835\udeb2<\/mi><\/mrow>=<\/mo>diag<\/mo>(<\/mo>\u03bb<\/mi>i<\/mi><\/msub>)<\/mo><\/mrow>\\boldsymbol{\\Lambda}=\\operatorname{diag}(\\lambda_i)<\/annotation><\/semantics><\/math> the characteristic values (poles) and \ud835\udc11<\/mi><\/mrow>\\mathbf{R}<\/annotation><\/semantics><\/math> whatever no linear model of the record explains: noise, unmeasured forcing, nonlinearity. The first identity is always exact; the second is exact for a clean linear record, and each pole is paired with its shape by construction.<\/p>\n\n\n\n
\"Animation:
With non-proportional damping a mode is complex: the station phasors form a polygon that rotates and shrinks, and the motion is its real part, so the nodes travel.<\/figcaption><\/figure>\n\n\n\n

<\/span>The readout<\/p>\n\n\n\n

Rotating by the eigenvectors of the coupling matrix makes the decomposition exact<\/h2>\n\n\n\n

The decomposition builds on the characteristic value decomposition (CVD\/GCVD) of Li, Stein and Chelidze (2025). It forms the same balanced quotient of second moments and its eigenvectors \ud835\udc15<\/mi><\/mrow>\\mathbf{V}<\/annotation><\/semantics><\/math>, then diagonalises the coupling matrix and rotates:<\/p>\n\n\n\n\ud835\udeba<\/mi><\/mrow>2<\/mn><\/msub>=<\/mo>𝐕<\/mi>𝖧<\/mi><\/mrow><\/msup>𝐁<\/mi>𝐕<\/mi>−<\/mo>𝖧<\/mi><\/mrow><\/msup>=<\/mo>𝐓<\/mi>\ud835\udeb2<\/mi><\/mrow>𝐓<\/mi>−<\/mo>1<\/mn><\/mrow><\/msup>,<\/mo>𝐔<\/mi>=<\/mo>\ud835\udeb5<\/mi><\/mrow>𝐓<\/mi>,<\/mo>\ud835\udebd<\/mi><\/mrow>=<\/mo>𝐕<\/mi>𝐓<\/mi>−<\/mo>𝖧<\/mi><\/mrow><\/msup><\/mrow>\\boldsymbol{\\Sigma}_2=\\mathbf{V}^{\\mathsf{H}}\\mathbf{B}\\,\\mathbf{V}^{-\\mathsf{H}}=\\mathbf{T}\\boldsymbol{\\Lambda}\\mathbf{T}^{-1},\\qquad \\mathbf{U}=\\boldsymbol{\\Xi}\\,\\mathbf{T},\\qquad \\boldsymbol{\\Phi}=\\mathbf{V}\\,\\mathbf{T}^{-\\mathsf{H}}<\/annotation><\/semantics><\/math>\n\n\n\n

The values are then the eigenvalues of the least-squares state-rate operator \ud835\udc01<\/mi>=<\/mo>\ud835\udc17<\/mi>1<\/mn>\u2020<\/mi><\/mrow><\/msubsup>\ud835\udc17<\/mi>2<\/mn><\/msub><\/mrow>\\mathbf{B}=\\mathbf{X}_1^{\\dagger}\\mathbf{X}_2<\/annotation><\/semantics><\/math>. Reading them from the diagonal of \ud835\udeba<\/mi><\/mrow>2<\/mn><\/msub><\/mrow>\\boldsymbol{\\Sigma}_2<\/annotation><\/semantics><\/math> instead is exact only when \ud835\udc15<\/mi><\/mrow>\\mathbf{V}<\/annotation><\/semantics><\/math> already diagonalises it. The balanced quotient applies the Joukowski map \u03bb<\/mi>\u21a6<\/mo>1<\/mn>2<\/mn><\/mfrac><\/mstyle>(<\/mo>\u03bb<\/mi>+<\/mo>\u03bb<\/mi>\u2212<\/mo>1<\/mn><\/mrow><\/msup>)<\/mo><\/mrow>\\lambda\\mapsto\\tfrac12(\\lambda+\\lambda^{-1})<\/annotation><\/semantics><\/math>, which folds the pole plane at the unit circle; averaged ensemble quotients and nonlinear windows also break diagonality. There the diagonal readout errs at second order in the poles and first order in the shapes.<\/p>\n\n\n\n
\"Animation:
Rescaling time moves the poles across the unit circle; where a pole meets its conjugate under the balanced map, the off-diagonal part of the coupling matrix spikes.<\/figcaption><\/figure>\n\n\n\n
\"Published
Left: an exact tie at a unit natural frequency. Right: windows of a nonlinear decay; pole differences scale with the square of the off-diagonal ratio, shape differences with its first power.<\/figcaption><\/figure>\n\n\n\n

<\/span>Practical data<\/p>\n\n\n\n

Derivatives, sensor noise, forcing and many records<\/h2>\n\n\n\n
Your data<\/th>Use<\/th><\/tr><\/thead>
Displacement, velocity and acceleration<\/td>ncvd(d, v, a)<\/code><\/td><\/tr>
Displacement only<\/td>state_from_displacement, then correct_poles<\/code><\/td><\/tr>
White sensor noise, sampling well above the highest mode<\/td>operator='bcls', noise_var='auto'<\/code><\/td><\/tr>
Measured excitation<\/td>forcing=F<\/code><\/td><\/tr>
Several records at any sampling rates<\/td>ncvd_ensemble(records)<\/code><\/td><\/tr>
Spectrum spanning decades<\/td>rank=r<\/code><\/td><\/tr>
Nonlinear free decay<\/td>track(d, v, a, ...)<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Rates computed from displacement by any FIR stencil return the stencil symbol of the pole, not the pole itself:<\/p>\n\n\n\nλ<\/mi>~<\/mo><\/mover>=<\/mo>d<\/mi>(<\/mo>e<\/mi>λ<\/mi>Δ<\/mi>t<\/mi><\/mrow><\/msup>)<\/mo><\/mrow>,<\/mo>d<\/mi>(<\/mo>θ<\/mi>)<\/mo>=<\/mo>f<\/mi>s<\/mi><\/msub>∑<\/mo>j<\/mi><\/munder>c<\/mi>j<\/mi><\/msub>θ<\/mi>j<\/mi><\/mrow><\/msup>,<\/mo>λ<\/mi>=<\/mo>f<\/mi>s<\/mi><\/msub>log<\/mi>θ<\/mi><\/mrow>\\tilde\\lambda=d\\!\\left(e^{\\lambda\\Delta t}\\right),\\qquad d(\\theta)=f_s\\sum_j c_j\\,\\theta^{j},\\qquad \\lambda=f_s\\log\\theta<\/annotation><\/semantics><\/math>\n\n\n\n

Inverting the symbol recovers the pole to machine precision for forward, central, five-point and Savitzky\u2013Golay stencils, inside each stencil’s band.<\/p>\n\n\n\n

\"Pole
Three-mass chain with modes at 4.2, 71 and 158 rad\/s. Solid: poles from FIR rates. Dotted: after correction.<\/figcaption><\/figure>\n\n\n\n
\"Frequency
Ten-mass chain under unmeasured random forcing with noise on every channel. Bias-compensated least squares keeps the frequency error below 2 % down to 15 dB, where least squares reaches 10 %.<\/figcaption><\/figure>\n\n\n\n

<\/span>Nonlinear systems<\/p>\n\n\n\n

Sliding windows trace frequency-energy dependence from one free decay<\/h2>\n\n\n\n

Each short window of a decay is decomposed; its values are the best linear description of the local dynamics. Following each resonance through the windows gives the data-driven counterpart of a nonlinear normal mode backbone curve, and the window residual shows how strongly each window engages the nonlinearity.<\/p>\n\n\n\n

\"Frequency
Damped frequency against modal energy, normalised by the linear value; crosses are the measured response frequency of mode 1 in each window.<\/figcaption><\/figure>\n\n\n\n
    \n
  1. Excite every resonance you track<\/strong>; check the singular values of each window.<\/li>\n\n\n\n
  2. Span at least one period<\/strong> of the slowest mode per window; a dozen is comfortable.<\/li>\n\n\n\n
  3. Watch weak modes<\/strong>: a superharmonic of a strong mode can take a weak mode’s pole slot.<\/li>\n\n\n\n
  4. Validate every pole<\/strong> against the measured response frequency (band_frequency<\/code>).<\/li>\n\n\n\n
  5. Trust frequencies and shapes<\/strong>; damping from single nonlinear windows scatters.<\/li>\n<\/ol>\n\n\n\n

    <\/span>Get started<\/p>\n\n\n\n

    Using the code<\/h2>\n\n\n\n

    Python (NumPy and SciPy):<\/p>\n\n\n\n

    git clone https:\/\/github.com\/nld-uri\/ncvd-toolbox.git\ncd ncvd-toolbox\/python && pip install -e .\n\nimport ncvd as nc\nrec = nc.ncvd(d, v, a)                  # X1 = U Phi^H, X2 = U Lam Phi^H + R\nmp  = nc.modal_parameters(rec.lam)      # wn, wd, zeta\ntr  = nc.track(d, v, a, fs=fs, length=800, step=400, M=M)   # backbones<\/code><\/pre>\n\n\n\n
    MATLAB (base MATLAB, R2022a or later):<\/p>\n\n\n\n
    addpath('ncvd-toolbox\/matlab')\nrec = ncvd.decompose(d, v, a);\nmp  = ncvd.modalParameters(rec.lam);\ntr  = ncvd.track(d, v, a, Fs=fs, Length=800, Step=400, M=M);<\/code><\/pre>\n\n\n\n
    Both packages share the same API and are tested against each other. The user manual<\/a> covers the theory, the options and seven worked examples; the repository README<\/a> lists the contents.<\/p>\n\n\n\n
    <\/span>Citation<\/p>\n\n\n\n
    How to cite<\/h2>\n\n\n\n
    Please cite both the software, archived on Zenodo as doi:10.5281\/zenodo.23549069<\/a>, and the method paper. ncvd.cite()<\/code> in Python and ncvd.cite<\/code> in MATLAB print the entries below.<\/p>\n\n\n\n
    @software{chelidze2026ncvd,\n  author    = {Chelidze, David and Li, Hewenxuan and Stein, Dalton L.},\n  title     = {{NCVD} toolbox: Nonlinear Characteristic Value Decomposition for {Python} and {MATLAB}},\n  version   = {1.0.0},\n  year      = {2026},\n  publisher = {Zenodo},\n  doi       = {10.5281\/zenodo.23549069},\n  url       = {https:\/\/github.com\/nld-uri\/ncvd-toolbox}\n}\n\n@article{li2025cvd,\n  author  = {Li, Hewenxuan and Stein, Dalton L. and Chelidze, David},\n  title   = {Characteristic value decomposition: A unifying paradigm for data-driven modal analysis},\n  journal = {Mechanical Systems and Signal Processing},\n  volume  = {222},\n  pages   = {111769},\n  year    = {2025},\n  doi     = {10.1016\/j.ymssp.2024.111769}\n}<\/code><\/pre>\n\n\n\n
    For amplitude-dependent identification and the reduced-order-model tools, please also cite D. L. Stein, D. Chelidze, Nonlinear Dynamics<\/em> 113 (2025) 25\u201345, doi:10.1007\/s11071-024-10239-0<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Nonlinear Dynamics Laboratory NCVD toolbox One free decay of a three-mass chain with a cubic spring. Each shaded window is decomposed; the three resonances trace their frequency-energy dependence back to the linear frequencies. Nonlinear Characteristic Value Decomposition: modal identification from a measured or simulated state record, with exact identities, pole correction for numerical derivatives, noise-robust […]<\/p>\n","protected":false},"author":1291,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"footnotes":"","_links_to":"","_links_to_target":""},"class_list":["post-1923","page","type-page","status-publish","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/pages\/1923","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/users\/1291"}],"replies":[{"embeddable":true,"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/comments?post=1923"}],"version-history":[{"count":4,"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/pages\/1923\/revisions"}],"predecessor-version":[{"id":1936,"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/pages\/1923\/revisions\/1936"}],"wp:attachment":[{"href":"https:\/\/web.uri.edu\/nld\/wp-json\/wp\/v2\/media?parent=1923"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}