{"record":{"id":"b8fe2a5070c6a1e5","repo":"TheAlgorithms/Java","slug":"damping-coefficient-must-be-non-negative","errorCode":null,"errorMessage":"Damping coefficient must be non-negative.","messagePattern":"Damping coefficient must be non-negative\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/thealgorithms/physics/DampedOscillator.java","lineNumber":53,"sourceCode":"    private final double gamma;\n\n    private DampedOscillator() {\n        throw new AssertionError(\"No instances.\");\n    }\n\n    /**\n     * Constructs a damped oscillator model.\n     *\n     * @param omega0 the natural frequency (rad/s), must be positive\n     * @param gamma  the damping coefficient (s⁻¹), must be non-negative\n     * @throws IllegalArgumentException if parameters are invalid\n     */\n    public DampedOscillator(double omega0, double gamma) {\n        if (omega0 <= 0) {\n            throw new IllegalArgumentException(\"Natural frequency must be positive.\");\n        }\n        if (gamma < 0) {\n            throw new IllegalArgumentException(\"Damping coefficient must be non-negative.\");\n        }\n        this.omega0 = omega0;\n        this.gamma = gamma;\n    }\n\n    /**\n     * Computes the analytical displacement of an underdamped oscillator.\n     * Formula: x(t) = A * exp(-γt) * cos(ω_d t + φ)\n     *\n     * @param amplitude the initial amplitude A\n     * @param phase     the initial phase φ (radians)\n     * @param time      the time t (seconds)\n     * @return the displacement x(t)\n     */\n    public double displacementAnalytical(double amplitude, double phase, double time) {\n        double omegaD = Math.sqrt(Math.max(0.0, omega0 * omega0 - gamma * gamma));\n        return amplitude * Math.exp(-gamma * time) * Math.cos(omegaD * time + phase);\n    }","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/TheAlgorithms/Java/blob/fdfb9a395b310167a66bd29e311e36e0e3e9b964/src/main/java/com/thealgorithms/physics/DampedOscillator.java#L35-L71","documentation":"Thrown by the DampedOscillator constructor when gamma < 0. The damping coefficient gamma (s^-1) represents energy dissipation; a negative value would imply energy injection (negative damping), which is physically unstable and produces exponentially growing oscillations in the analytical formula. This guard runs after the omega0 check, so omega0 must already be valid.","triggerScenarios":"Calling new DampedOscillator(omega0, gamma) with a negative gamma. A gamma of exactly 0 is allowed and models the undamped case; only strictly negative values throw.","commonSituations":"Sign error when computing gamma from measured Q-factor (gamma = omega0/Q), passing a negative friction/viscosity constant, or feeding raw sensor data that contained a negative slope.","solutions":["Pass gamma >= 0; use 0 for an undamped oscillator and a small positive value for light damping.","If gamma is derived from a measurement, apply Math.abs or validate sign at the source rather than relying on the constructor to fail.","Re-check the formula gamma = omega0 / Q — a Q below 1 still yields positive gamma, but a sign flip elsewhere can produce a negative."],"exampleFix":"// before\nDampedOscillator osc = new DampedOscillator(2 * Math.PI, -0.5);\n// after\nDampedOscillator osc = new DampedOscillator(2 * Math.PI, 0.5);","handlingStrategy":"validation","validationCode":"if (gamma < 0) {\n    gamma = Math.abs(gamma); // or throw, depending on domain\n}\nDampedOscillator osc = new DampedOscillator(omega0, gamma);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When deriving gamma from a Q-factor, validate the sign at the source.","Use 0 to model the undamped case rather than a tiny negative value.","Validate the full (omega0, gamma) pair together before constructing."],"tags":["java","physics","parameter-validation","oscillator","constructor","illegal-argument"],"backgroundTag":null,"analyzedSha":"fdfb9a395b310167a66bd29e311e36e0e3e9b964","analyzedAt":"2026-08-13T23:36:13.315Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}