Installation

Terminal

npm install atmospheris

Works with Node.js, browser bundlers (Vite, Webpack), and Deno. Full TypeScript type definitions included.

Quick Start

index.ts

import { getAllProperties, getAltitudeFromPressure, computeWindDerived } from "atmospheris"

// Get all properties at 10,000 m geopotential altitude
const result = getAllProperties({
  value: 10000,
  unit: "meters",
  type: "geopotential",
  precision: "normal"
})

console.log(result.temperature.kelvin)    // 223.252
console.log(result.pressure.mbar)         // 264.36
console.log(result.density)               // 0.4135
console.log(result.speedOfSound)          // 299.46

// Reverse lookup: pressure to altitude
const alt = getAltitudeFromPressure({
  value: 264.36,
  unit: "mbar"
})
console.log(alt.geopotentialAltitude.meters) // ~10000

// Wind distribution (ISO 5878)
const wind = computeWindDerived(-3.9, -1.2, 5.9)
console.log(wind.Vsc)                     // 6.03 m/s

API Reference

`getAllProperties(input)`

Calculates all atmospheric properties at a given altitude. Returns an object with temperature, pressure, density, viscosity, speed of sound, and 15 additional derived properties — 19 properties in total, matching the three property groups defined in ISO 2533 Tables 5–7.

types.d.ts

interface AltitudeInput {
  value: number          // Altitude value
  unit: "meters" | "feet"
  type: "geopotential" | "geometric"
  precision?: "normal" | "reduced"  // default: "normal"
}

interface AltitudeResult {
  geopotentialAltitude: { meters: number; feet: number }
  geometricAltitude: { meters: number; feet: number }
  temperature: { kelvin: number; celsius: number; fahrenheit: number; rankine: number }
  temperatureRatio: number
  molecularTemperature: number
  lapseRate: number
  pressure: { pascal: number; mbar: number; mmHg: number }
  pressureRatio: number
  density: number
  densityRatio: number
  sqrtDensityRatio: number
  gravity: number
  gravityRatio: number
  speedOfSound: number
  speedOfSoundRatio: number
  dynamicViscosity: number
  dynamicViscosityRatio: number
  kinematicViscosity: number
  kinematicViscosityRatio: number
  thermalConductivity: number
  thermalConductivityRatio: number
  pressureScaleHeight: number
  specificWeight: number
  airNumberDensity: number
  meanParticleSpeed: number
  collisionFrequency: number
  meanFreePath: number
  moleVolume: number
}

`getAltitudeFromPressure(input)`

Reverse lookup: finds the geopotential and geometric altitude corresponding to a given atmospheric pressure. This implements the hypsometrical equation from ISO 2533 Addendum 1:1985.

interface PressureInput {
  value: number
  unit: "mbar" | "mmHg"
  precision?: "normal" | "reduced"
}

interface PressureResult {
  geopotentialAltitude: { meters: number; feet: number }
  geometricAltitude: { meters: number; feet: number }
  pressure: { mbar: number; mmHg: number }
}

`getAltitudeFromProperty(input)`

Bidirectional solver: given any of the 28 supported atmospheric property values (temperature, pressure, density, viscosity, speed of sound, etc.), finds the corresponding altitude and returns all properties at that altitude. Useful when you know a target condition (e.g. "at what altitude is the speed of sound 295 m/s?") rather than the altitude itself.

import { getAltitudeFromProperty } from "atmospheris"

// At what altitude is temperature -56.5 °C?
const result = getAltitudeFromProperty({
  mode: "property",
  property: "temperature_c",
  value: -56.5,
  precision: "normal"
})
// result.geopotentialAltitude.meters => ~11000 (tropopause)

// At what altitude is density 0.1 kg/m³?
const r2 = getAltitudeFromProperty({
  mode: "property",
  property: "density_kgm3",
  value: 0.1
})

The property field accepts any of the 28 property identifiers (e.g. "temperature_k", "pressure_mbar", "speed_of_sound_ms", "dynamic_viscosity", "air_number_density", etc.). Returns the same AltitudeResult as getAllProperties.

`computeWindDerived(vx, vy, sigmaR, options?)`

Computes derived wind characteristics from observed zonal and meridional wind components using the Rice (circular normal) distribution model defined in ISO 5878 Section 5.4. Returns scalar mean wind speed, per-component standard deviation, and wind speeds at six percentile levels (1%, 10%, 20%, 80%, 90%, 99%).

import { computeWindDerived } from "atmospheris"

const wind = computeWindDerived(-3.9, -1.2, 5.9)
// wind.Vr     => 4.08 — vector mean wind magnitude
// wind.Vsc    => 6.03 — scalar mean wind speed
// wind.sigma  => 4.17 — per-component std deviation
// wind.percentiles["1"]  => { low: ~0.1, high: ~14.7 }
// wind.percentiles["10"] => { low: ~0.5, high: ~12.0 }
// wind.percentiles["20"] => { low: ~1.2, high: ~10.5 }

For latitude zones above 20°N where the meridional component Vy is negligible, pass { useAbsoluteVx: true } to use |Vx| as Vr directly.

`RiceDistribution`

Object-oriented wrapper that encapsulates a Rice distribution with fixed parameters, providing lazy-cached PDF, CDF, quantile, mean, and percentile computations:

import { RiceDistribution } from "atmospheris"

const dist = new RiceDistribution(4.08, 5.9)
dist.mean()              // Vsc ≈ 6.03 m/s
dist.pdf(5.0)            // probability density at 5 m/s
dist.cdf(10.0)           // P(wind ≤ 10 m/s)
dist.quantile(0.99)      // wind speed exceeded on 1% of occasions
dist.percentileBounds()  // { 1: {low,high}, 10: {low,high}, 20: {low,high} }

`WindObservation`

Encapsulates a single altitude-level wind observation with empirically measured parameters and lazily computed derived statistics:

import { WindObservation } from "atmospheris"

const obs = new WindObservation({
  geopotentialAltitude: 1000,
  vx: -3.9, vy: -1.2, sigmaR: 5.9
})
obs.vr                        // 4.08 — vector mean wind magnitude
obs.vsc                       // 6.03 — calculated scalar mean speed
obs.percentileBounds[1].high  // ~14.7

Low-level wind functions

The underlying mathematical functions are also exported for advanced use:

import {
  besselI0, besselI1,     // Modified Bessel functions (Abramowitz & Stegun)
  ricePdf, riceCdf,       // Rice distribution PDF and CDF
  riceInvCdf,             // Rice inverse CDF (quantile)
  riceMean,               // Rice analytical mean (ISO 5878 Eq. 4)
} from "atmospheris"

Constants & Layers

The library exports the fundamental ISA constants and temperature layer definitions for direct use in calculations or display:

import { CONSTANTS, DERIVED_CONSTANTS, TEMPERATURE_LAYERS } from "atmospheris"

CONSTANTS.g_n         // 9.80665 m/s² — standard gravitational acceleration
CONSTANTS.T_n         // 288.15 K — standard temperature
CONSTANTS.p_n         // 101325 Pa — standard pressure
CONSTANTS.rho_n       // 1.225 kg/m³ — standard density
CONSTANTS.R_star      // 8.31432 J/(mol·K) — universal gas constant
CONSTANTS.N_A         // 6.02257e+26 mol⁻¹ — Avogadro constant
CONSTANTS.radius      // 6356766 m — nominal Earth radius
CONSTANTS.kappa       // 1.4 — adiabatic index

DERIVED_CONSTANTS.M   // ~0.028964 kg/mol — molar mass of dry air
DERIVED_CONSTANTS.R   // ~287.052 J/(kg·K) — specific gas constant

// 9 temperature layers, each with { H, T, B } (base altitude, temperature, lapse rate)
TEMPERATURE_LAYERS.forEach(l => console.log(l.H, l.T, l.B))

TypeScript / JavaScript