algorithms.eam_reader Module

Atmosphere Data - Readers and Filters for ParaView

This module provides NetCDF readers and filters for E3SM/EAM (Energy Exascale Earth System Model / E3SM Atmosphere Model) data visualization in ParaView.

Dependencies

• netCDF4: For reading NetCDF climate data files

• numpy: For numerical array operations

• math: Standard library for spherical coordinate transformations

No external dependencies like pyproj or pandas are required.

Readers

EAMDataReader

Multi-output reader that produces three separate outputs: - Port 0: Surface variables (e.g., surface temperature, precipitation) - Port 1: Middle layer variables on lev levels as hexahedral volume mesh - Port 2: Interface layer variables on ilev levels as hexahedral volume mesh

Filters

EAMProjectToSphere

Projects lat/lon data onto a 3D sphere for globe visualization. Supports scaling for vertical exaggeration of atmospheric layers.

Data Format

EAM/E3SM data consists of:

• Data files (.nc): NetCDF files containing time-varying atmospheric variables

• Connectivity files (.nc): NetCDF files defining the unstructured mesh topology with corner lat/lon coordinates for each grid cell

The readers automatically detect:

• Horizontal dimensions by matching sizes between connectivity and data files

• Vertical dimensions (lev for mid-levels, ilev for interface levels)

• Time dimensions for animation support

• Fill values (_FillValue or missing_value attributes)

Vertical Coordinates

EAM uses hybrid sigma-pressure coordinates. The readers can compute pressure levels from hybrid coefficients (hyam, hybm, hyai, hybi) if explicit level coordinates are not provided.

Usage Example

In ParaView:

1. Use File -> Open to select a NetCDF data file

2. Choose “EAM Data Reader”

3. Set the connectivity file path in the Properties panel

4. Select variables to load from the array selection widgets

5. Apply to visualize

For spherical projection:

1. Apply EAMDataReader reader

2. Apply EAMProjectToSphere filter

3. Adjust scale factor for vertical exaggeration if needed

class paraview.algorithms.eam_reader.AtmosphereConstants

Bases: object

Constants for EAM atmospheric model hybrid coordinates.

HYAI = 'hyai'

HYAM = 'hyam'

HYBI = 'hybi'

HYBM = 'hybm'

ILEV = 'ilev'

LEV = 'lev'

P0 = 100000.0

PS0 = 100000.0

class paraview.algorithms.eam_reader.DimMeta(name, size, data=None)

Bases: object

Stores dimension metadata from NetCDF files.

update_from_variable(var_info)

Update metadata from netCDF variable info.

class paraview.algorithms.eam_reader.EAMDataReader

Bases: VTKPythonAlgorithmBase

Multi-output NetCDF reader for E3SM/EAM atmospheric model data.

This reader produces three separate outputs for different variable types: - Port 0 (Surface): Surface variables with 2 dimensions (time, ncol) as quad mesh - Port 1 (Middle Layer): Variables on middle levels as hexahedral volume mesh - Port 2 (Interface Layer): Variables on interface levels as hexahedral volume mesh

The 3D outputs are converted to volumetric data directly in the reader, producing hexahedral cells that span between adjacent vertical levels. This enables immediate volume rendering without requiring additional filters.

The reader automatically detects horizontal dimensions by matching the connectivity file’s cell count with dimensions in the data file. It handles fill values (_FillValue, missing_value) by converting them to NaN.

Parameters

DataFilestr

Path to the NetCDF data file containing atmospheric variables.

ConnectivityFilestr

Path to the NetCDF connectivity file containing mesh topology (corner_lat, corner_lon arrays defining cell vertices).

Outputs

Port 0vtkUnstructuredGrid

Surface mesh with quad cells. Each cell corresponds to one horizontal grid column. Contains selected surface variables as cell data.

Port 1vtkUnstructuredGrid

Volumetric mesh for middle layer (lev) variables with hexahedral cells. Cell data is averaged between adjacent levels. Contains ‘lev’ and ‘numlev’ in field data.

Port 2vtkUnstructuredGrid

Volumetric mesh for interface layer (ilev) variables with hexahedral cells. Cell data is averaged between adjacent levels. Contains ‘ilev’ and ‘numilev’ in field data.

Notes

• Vertical coordinates are computed from hybrid sigma-pressure coefficients (hyam, hybm for lev; hyai, hybi for ilev) if explicit level arrays are missing.

• The reader caches NetCDF file handles to avoid repeated file opens.

• Variables are grouped by type in the ParaView UI for easy selection.

• Time dimension is automatically detected and exposed for animation.

• 3D outputs have (num_levels - 1) hexahedral cells in the vertical direction since each hex spans two adjacent levels.

Example

In ParaView Python shell:

from paraview.simple import EAMDataReader
reader = EAMDataReader()
reader.DataFile = '/path/to/data.nc'
reader.ConnectivityFile = '/path/to/connectivity.nc'
reader.SurfaceVariables = ['TREFHT']
reader.UpdatePipeline()

GetInterfaceLayerDataArrays()

GetMiddleLayerDataArrays()

GetSurfaceDataArrays()

GetTimestepValues()

RequestData(request, inInfo, outInfo)

Overwritten by subclass to execute the algorithm.

RequestInformation(request, inInfo, outInfo)

Overwritten by subclass to provide meta-data to downstream pipeline.

SetConnectivityFileName(fname)

SetDataFileName(fname)

class paraview.algorithms.eam_reader.EAMProjectToSphere

Bases: VTKPythonAlgorithmBase

Project lat/lon data onto a 3D sphere for globe visualization.

This filter transforms points from geographic coordinates (longitude as X, latitude as Y, vertical level as Z) into spherical coordinates for rendering data on a 3D globe. It supports vertical exaggeration through a scale factor to make atmospheric layers visible.

The transformation maps:

• Longitude -> azimuthal angle (theta)

• Latitude -> polar angle (phi), measured from north pole

• Z-coordinate -> radial distance from sphere center

Parameters

Data Layerbool

If True, adds a small offset (1 unit) to the radius. This is useful when overlaying data on a separate sphere geometry to prevent z-fighting artifacts. Default is False.

Scalefloat

Vertical exaggeration factor for the Z-coordinate. Higher values make vertical structure more visible. Default is 1.0. A value of 0 places all points on the sphere surface.

Input

vtkUnstructuredGrid or vtkPolyData

Mesh with points in geographic coordinates.

• X: Longitude in degrees (-180 to 180 or 0 to 360)

• Y: Latitude in degrees (-90 to 90)

• Z: Vertical level (e.g., pressure in hPa, or index)

Output

vtkUnstructuredGrid

Same topology as input but with points transformed to spherical coordinates. Point data and cell data are preserved unchanged.

Notes

• The default sphere radius is 2000 units, designed for visualization with typical atmospheric data scales.

• For 2D surface data (Z=0), all points are placed exactly on the sphere.

• For 3D data, higher Z values (e.g., higher pressure = lower altitude) result in smaller radii, placing those points closer to the sphere center.

• vtkPolyData input is automatically converted to vtkUnstructuredGrid.

Example

In ParaView Python shell:

from paraview.simple import *
reader = EAMDataReader()
reader.DataFile = '/path/to/data.nc'
reader.ConnectivityFile = '/path/to/connectivity.nc'
reader.SurfaceVariables = ['TREFHT']
reader.Update()

# Project surface output onto sphere
sphere = EAMProjectToSphere(Input=OutputPort(reader, 0))
sphere.DataLayer = True  # Slight offset for layering
sphere.Update()

# For middle layer data with vertical exaggeration
sphere3d = EAMProjectToSphere(Input=OutputPort(reader, 1))
sphere3d.Scale = 10.0  # Exaggerate vertical structure
sphere3d.Update()

FillInputPortInformation(port, info)

Sets the required input type to InputType.

RequestData(request, inInfo, outInfo)

Overwritten by subclass to execute the algorithm.

RequestDataObject(request, inInfo, outInfo)

Overwritten by subclass to manage data object creation. There is not need to overwrite this class if the output can be created based on the OutputType data member.

SetDataLayer(is_data)

SetScalingFactor(scale)

paraview.algorithms.eam_reader.FindSpecialVariable(data, lev, hya, hyb)

Find or compute level coordinates from hybrid coefficients.

class paraview.algorithms.eam_reader.VarMeta(name, info, horizontal_dim=None)

Bases: object

Stores variable metadata from NetCDF files.

get_vertical_dim()

Return the vertical dimension (lev or ilev) if present.

has_dim(dim_name)

Check if variable has a specific dimension.

paraview.algorithms.eam_reader.build_2d_geometry(lat, lon, ncells)

Build VTK geometry arrays for 2D mesh.

paraview.algorithms.eam_reader.build_3d_volume_geometry(lat, lon, levels, ncells2d)

Build VTK geometry arrays for 3D volumetric mesh with hexahedral cells.

Creates hexahedra by connecting adjacent vertical layers. Each hex cell spans from level N to level N+1, resulting in (num_levels - 1) layers of hexahedral cells.

Parameters

latndarray

Flattened latitude coordinates for cell corners.

lonndarray

Flattened longitude coordinates for cell corners.

levelsndarray

Vertical level coordinates.

ncells2dint

Number of 2D cells per horizontal layer.

Returns

vtk_coordsvtkPoints

Points for all vertical levels.

cell_typesvtkUnsignedCharArray

Cell type array (all VTK_HEXAHEDRON).

cell_arrayvtkCellArray

Cell connectivity array.

paraview.algorithms.eam_reader.compare(data, arrays, dim)

Compare arrays for hybrid coordinate validation.

paraview.algorithms.eam_reader.createModifiedCallback(anobject)

Create a weak-reference callback for ParaView modified events.

paraview.algorithms.eam_reader.find_lat_lon_vars(meshdata)

Find lat/lon variable names in connectivity file.

paraview.algorithms.eam_reader.identify_horizontal_dim(meshdata, vardata)

Identify horizontal dimension from connectivity file and match in data file. Returns (conn_dim_name, data_dim_name, size) or (None, None, None) on failure.

paraview.algorithms.eam_reader.load_variable_data(vardata, varmeta, time_idx)

Load variable data for a given time index, handling transpose and fill values.

paraview.algorithms.eam_reader.load_variable_data_averaged(vardata, varmeta, time_idx, ncells2d, nlev)

Load 3D variable data and average between adjacent vertical levels.

For hexahedral cells that span between levels N and N+1, the cell data is computed as the average of the values at those two levels.

Parameters

vardatanetCDF4.Dataset

NetCDF dataset containing the variable.

varmetaVarMeta

Variable metadata.

time_idxint

Time index to load.

ncells2dint

Number of 2D cells per horizontal layer.

nlevint

Number of vertical levels in the data.

Returns

ndarray

Averaged cell data with shape (nlev-1) * ncells2d.

paraview.algorithms.eam_reader.process_point_to_sphere(point, max_z, radius, scale)

Convert lat/lon/z point to spherical coordinates.