Hidden Assumptions in neuralgcm
13 assumptions this code never checks · 5 critical · spanning Shape, Domain, Scale, Ordering, Contract, Temporal, Resource, Environment
Every codebase relies on things it never checks. Most of them are routine. CodeSea looked at neuralgcm/neuralgcm and picked out the few most likely to cause trouble. The full list is just below.
Most of what this code assumes is routine. These 3 are the ones most likely to cause trouble here. The rest are minor; they're under "Show everything".
If pressure levels are not monotonic (e.g., due to numerical errors or incorrect data), jnp.searchsorted produces wrong indices leading to interpolation to wrong pressure levels, causing physically impossible temperature/wind profiles
If training data uses different variable names (e.g., 'u_wind' vs 'u_component_of_wind'), the operator silently produces wrong observation mappings, causing the model to train on incorrect variable associations
If the model is configured with a different number of vertical levels or pressure units differ from the hardcoded reference, array indexing fails or physical calculations use wrong pressure values, corrupting thermodynamic computations
Show everything (10 more)
The neural parameterization expects spherical harmonic coefficients to be ordered consistently with the ylm_map coordinate system, particularly that wavenumber indices match between input data and the mapping
If this fails: If input coefficients have different wavenumber ordering than expected by ylm_map, the neural network processes wrong spectral components, leading to physically inconsistent tendency predictions that violate conservation laws
neuralgcm/experimental/atmosphere/parameterizations.py:ModalNeuralDivCurlParameterization
FixerModule protocol assumes that diagnostic fields and target fields have identical coordinate systems and that the diagnostic calculation succeeded without NaN/inf values
If this fails: If diagnostics contain NaN/inf due to numerical instability or coordinate mismatches, the fixer propagates these bad values into tendency corrections, causing the entire simulation to diverge
neuralgcm/experimental/atmosphere/fixers.py:FixerModule
Energy balance adjustments assume that energy imbalances represent steady-state errors rather than transient physical processes, and that redistributing energy preserves the model's temporal stability
If this fails: If energy imbalances arise from legitimate transient processes (e.g., during rapid weather transitions), forcing balance creates artificial energy redistributions that suppress realistic weather variability
neuralgcm/experimental/atmosphere/diagnostics.py:EnergyBalanceModule
Linear interpolation with extrapolation assumes that arrays fit in memory and that unlimited extrapolation won't produce values outside the valid physical range for atmospheric variables
If this fails: Extrapolation can produce unphysical values like negative absolute temperatures or supersonic wind speeds that cause downstream numerical instability in physics computations
neuralgcm/experimental/atmosphere/interpolators.py:_linear_interp_with_linear_extrap
The regridding function assumes input datasets have coordinate dimensions named exactly 'longitude' and 'latitude', and that coordinate values are in the same units as expected by the regridder
If this fails: If input data uses different coordinate names or units (degrees vs radians), xarray.apply_ufunc fails to find the core dimensions or regridding operates on wrong coordinate values, producing geographically misplaced data
neuralgcm/demo.py:_horizontal_regrid
Demo functions assume that importlib.resources and pickle can successfully load packaged model data, and that the dinosaur library's coordinate systems are compatible with the loaded model configuration
If this fails: If package installation is incomplete or dinosaur version mismatches, demo fails with unclear import errors, making it impossible for users to verify basic functionality
neuralgcm/demo.py
Pressure interpolation assumes that the pressure range in input data covers the target pressure levels, but linear extrapolation is used without bounds checking for extreme values
If this fails: Extrapolating to pressure levels far outside the data range (e.g., stratosphere when data only covers troposphere) produces unphysical atmospheric profiles that violate hydrostatic balance
neuralgcm/experimental/atmosphere/interpolators.py:LinearOnPressure
The primitive equations module assumes that input atmospheric state fields have consistent physical units and that the coordinate system metadata correctly describes the spatial grid
If this fails: Unit inconsistencies or wrong coordinate metadata cause physics calculations to use incorrect scaling factors, leading to wrong magnitude tendencies that can destabilize the simulation
neuralgcm/experimental/atmosphere/equations.py:PrimitiveEquationsModule
The observation operator assumes that vertical levels in the atmospheric state are ordered consistently with the target observation data (either surface-to-top or top-to-surface)
If this fails: If vertical ordering differs between model and observations, computed observation variables have flipped vertical profiles, causing training to learn inverted atmospheric relationships
neuralgcm/experimental/atmosphere/observation_operators.py:StandardVariablesObservationOperator
Atmospheric diagnostics assume that all required state variables are present and physically meaningful, with no validation that computed diagnostics fall within realistic ranges for Earth's atmosphere
If this fails: Diagnostic calculations proceed even with unphysical input states, producing misleading diagnostic values that hide model problems and make it difficult to detect when the simulation has gone off track
neuralgcm/experimental/atmosphere/diagnostics.py
See the full structural analysis of neuralgcm: the pipeline, data models, and system behavior that put these assumptions in context.
Full analysis of neuralgcm/neuralgcm →Frequently Asked Questions
What does neuralgcm assume that could break in production?
The one most likely to cause trouble: LinearOnPressure expects input fields to have coordinates where vertical levels are sorted in ascending or descending order, and pressure values are monotonic If this fails, If pressure levels are not monotonic (e.g., due to numerical errors or incorrect data), jnp.searchsorted produces wrong indices leading to interpolation to wrong pressure levels, causing physically impossible temperature/wind profiles
How many hidden assumptions does neuralgcm have?
CodeSea found 13 assumptions neuralgcm relies on but never validates, 5 of them critical, spanning Shape, Domain, Scale, Ordering, Contract, Temporal, Resource, Environment. Most are routine — the analysis flags the two or three most likely to actually bite.
What is a hidden assumption?
Something the code depends on but never checks: a data shape, an ordering, an environment condition, a scale limit, or a contract with another service. It holds until the world it runs in changes, then fails silently.