Crate use_oscillation

Expand description

§use-oscillation

Oscillation and simple harmonic motion helpers for RustUse.

§Install

[dependencies]
use-oscillation = "0.0.1"

§Foundation

use-oscillation provides small scalar helpers for simple harmonic motion, period, frequency, angular frequency, spring oscillators, pendulum approximations, damping, resonance, and oscillator state summaries.

Inputs are expected to be SI-style numeric values:

seconds for period and time
hertz for frequency
radians per second for angular frequency
meters for displacement, amplitude, and pendulum length
kilograms for mass
newtons per meter for spring constant
meters per second squared for gravitational acceleration
joules for energy

Radians are used for phase.

§Example

use core::f64::consts::{PI, TAU};
use use_oscillation::{SimpleHarmonicOscillator, spring_period};

let oscillator = SimpleHarmonicOscillator::new(2.0, TAU, 0.0).unwrap();
let period = spring_period(8.0, 2.0).unwrap();

assert!((oscillator.displacement(0.0).unwrap() - 2.0).abs() < 1.0e-12);
assert!((period - PI).abs() < 1.0e-12);

§When to use directly

Choose use-oscillation when you only need reusable scalar helpers for simple oscillators.

§Scope

This crate stays f64-first and scalar-only.
It is not a wave library, signal-processing library, acoustics library, numerical simulator, or control-system package.
Wave abstractions belong in the top-level use-wave set.
Signal processing belongs in the top-level use-signal set.
Acoustics belongs in the top-level use-acoustics set.
Units belong in the top-level use-units set.

§Status

use-oscillation is a pre-1.0 crate with a deliberately small API. Oscillation-specific scalar helpers.

Modules§

prelude

Structs§

SimpleHarmonicOscillator: A simple scalar harmonic oscillator state.
SpringOscillator: A spring-mass oscillator state.

Functions§

acceleration: Computes acceleration for simple harmonic motion using a(t) = -Aω² * cos(ωt + φ).
acceleration_from_displacement: Computes simple-harmonic acceleration from displacement using a = -ω²x.
angular_frequency_from_frequency: Computes angular frequency from frequency using ω = 2πf.
angular_frequency_from_period: Computes angular frequency from period using ω = 2π / T.
critical_damping_coefficient: Computes the critical damping coefficient using c_critical = 2 * sqrt(mk).
damped_angular_frequency: Computes the damped angular frequency for an underdamped oscillator.
damping_ratio: Computes damping ratio using ζ = c / (2 * sqrt(mk)).
damping_ratio_from_quality_factor: Computes damping ratio from quality factor using ζ = 1 / (2Q).
displacement: Computes displacement for simple harmonic motion using x(t) = A * cos(ωt + φ).
frequency_from_angular_frequency: Computes frequency from angular frequency using f = ω / 2π.
frequency_from_period: Computes frequency from period using f = 1 / T.
is_critically_damped: Returns true when the damping ratio is within tolerance of critical damping.
is_overdamped: Returns true when the damping ratio represents an overdamped system.
is_underdamped: Returns true when the damping ratio represents an underdamped system.
kinetic_energy_from_total_and_potential: Computes kinetic energy from total energy and potential energy using KE = E_total - U.
mass_from_spring_period: Computes mass from spring constant and period using m = kT² / 4π².
max_acceleration: Computes the maximum acceleration using a_max = Aω².
max_speed: Computes the maximum speed using v_max = Aω.
oscillator_total_energy: Computes oscillator total energy using E = 0.5 * k * A².
pendulum_length_from_period: Computes pendulum length from period using L = g * (T / 2π)².
period_from_angular_frequency: Computes period from angular frequency using T = 2π / ω.
period_from_frequency: Computes period from frequency using T = 1 / f.
quality_factor_from_damping_ratio: Computes quality factor from damping ratio using Q = 1 / (2ζ).
resonance_angular_frequency_natural: Computes the natural resonance angular frequency of a spring-mass oscillator.
simple_pendulum_angular_frequency: Computes small-angle simple pendulum angular frequency using ω = sqrt(g / L).
simple_pendulum_frequency: Computes small-angle simple pendulum frequency in cycles per second.
simple_pendulum_period: Computes the small-angle simple pendulum period using T = 2π * sqrt(L / g).
spring_angular_frequency: Computes spring angular frequency using ω = sqrt(k / m).
spring_constant_from_period: Computes spring constant from mass and period using k = 4π²m / T².
spring_frequency: Computes spring frequency in cycles per second.
spring_period: Computes spring period using T = 2π * sqrt(m / k).
spring_potential_energy: Computes spring potential energy using U = 0.5 * k * x².
velocity: Computes velocity for simple harmonic motion using v(t) = -Aω * sin(ωt + φ).