polaris.ocean.vertical.pstar_init.PStarInitStep.run_pstar_init

PStarInitStep.run_pstar_init(ds_mesh: Dataset, geom_z_bot: DataArray, surface_pressure: DataArray | None = None, sea_surface_height: DataArray | None = None) → Dataset

Run the fixed-point iteration that determines BottomPressure (and therefore the p-star coordinate) such that the recovered geometric water-column thickness matches the target within a configurable fractional tolerance.

At convergence the returned dataset contains all p-star coordinate variables, converged tracer fields, specific volume, pressure, geometric height at layer midpoints and interfaces, ssh set to the prescribed sea_surface_height, and bottomDepth diagnosed as the geometric depth of the (surface-anchored) column. The two agree with the target bathymetry where the iteration converges; where partial-cell snapping prevents an exact match, the residual adjusts bottomDepth (the representable bathymetry) rather than ssh.

Parameters:

• ds_mesh (xarray.Dataset) – Horizontal mesh dataset.

• geom_z_bot (xarray.DataArray) – Target geometric height of the seafloor (negative, in metres) with dimension nCells. Used both to anchor geom_height_from_pseudo_height and to set the target water-column thickness.

• surface_pressure (xarray.DataArray, optional) – Sea-surface pressure (Pa) with dimension nCells. Defaults to zero for all cells.

• sea_surface_height (xarray.DataArray, optional) – Prescribed sea-surface height (m) with dimension nCells. The target water-column thickness is sea_surface_height - geom_z_bot; the iteration adjusts BottomPressure until this target is met, so the converged ssh equals this value. Defaults to -surface_pressure / (RhoSw * Gravity), i.e. the sea-surface depression that balances the surface pressure for a reference-density fluid. (Being at rest does not imply ssh = 0; surface loading depresses ssh even at rest.)

Returns:

xarray.Dataset – Dataset containing all base-class output variables with long_name and units attributes set.