Model State¶

A State object encapsulates a snapshot of the atmospheric state. It provides variables derived from the underlying PV field and convenience accessors to other functionality of barotropic.

State¶

class barotropic.State(grid, time, pv=None, pv_spectral=None)¶

Bases: object

Model field container for a barotropic atmosphere.

Parameters:

grid (Grid) – Grid description for contained fields.
time (number | datetime) – Valid time. Specify either a number in seconds or a datetime-like object.
pv (None | array) – Gridded field of potential vorticity (PV, absolute vorticity in the barotropic framework).
pv_spectral (None | array) – Spectral representation of potential vorticity. Only specify if pv is None.

Note

There are alternative classmethod constructors of State and the init module also provides functions to create State objects for model initialization.

Provides convenient access to fields, diagnostics and plots. Should generally be treated as an immutable object.

time¶: Valid time.

grid¶: Associated Grid object.

add_vorticity(other)¶

Relative vorticity-based addition of atmospheric states.

Parameters:: other (array | State) – other vorticity field in the addition. Specify directly as array or extracted from a given State object.
Returns:: New State instance.

add_wind(other)¶

Wind-based addition of atmospheric states.

Parameters:: other (tuple | State) – other wind field in the addition. Specify directly as (u,v)-tuple or extracted from a given State object.
Returns:: New State instance.

as_hn2016(**barofield_kwargs)¶

Convert state to a falwa Barotropic state.

Parameters:: barofield_kwargs – Keyword arguments given to the constructor.
Returns:: falwa.barotropic_field.BarotropicField instance.

Note

In falwa latitude starts at the South Pole, so array contents are meridionally flipped compared to barotropic.

See State.from_hn2016() for the inverse operation.

Requires falwa package.

property avo¶: Absolute vorticity (alias of pv).

Added in version 3.1.

property eddy_enstrophy¶: Enstropy after removal of the zonal-mean PV.

property energy¶: Kinetic energy of the flow.

property enstrophy¶: Enstropy = 0.5 * q² where q is PV.

extract_ks_waveguides(*args, **kwargs)¶: Shortcut to diagnostics.extract_ks_waveguides().

property falwa¶

Finite-Amplitude Local Wave Activity on the regular grid.

See diagnostics.falwa().

property falwa_filtered¶

Finite-Amplitude Local Wave Activity, phase-filtered based on v.

The FALWA field is filtered based on the doubled dominant wavenumber of the meridional wind obtained from Fourier analysis at each latitude as in Ghinassi et al. (2020).

See diagnostics.falwa(), diagnostics.dominant_wavenumber_fourier() and diagnostics.filter_by_wavenumber().

property fawa¶

Finite-Amplitude Wave Activity on the regular grid.

See diagnostics.fawa().

classmethod from_hn2016(grid, time, barofield)¶

Take PV from falwa barotropic state object.

Parameters:

grid (Grid | None) – Grid used for instantiated State. If None, a new Grid matching the input is created.
time (number | datetime) – Valid time as number in seconds or a datetime-like object.
barofield (falwa.barotropic_field.BarotropicField) – Instance from which to take PV field for instantiation.

Returns:

New State instance.

See State.as_hn2016() for the inverse operation.

classmethod from_vorticity(grid, time, vorticity)¶

Initialize a model state based on relative vorticity.

Parameters:

grid (Grid) – Given to the default constructor.
time (number | datetime) – Given to the default constructor.
vorticity (array) – Relative vorticity field for initialization.

Returns:

New State instance.

classmethod from_wind(grid, time, u, v)¶

Initialize a model state based on wind components.

Parameters:

grid (Grid) – Given to the default constructor.
time (number | datetime) – Given to the default constructor.
u (array) – Zonal wind component for initialization.
v (array) – Meridional wind component for initialization.

Returns:

New State instance.

property plot¶

Interface to plot presets from plot for interactive use.

Provides shortcuts to:

Plotters accessed through this interface do not return the Figure instance like their standalone versions from plot, which means that the created image is not displayed twice in the output of a jupyter notebook cell (once captured from within matplotlib and once as the returned object of the cell).

property pv¶: Barotropic potential vorticity (i.e. absolute vorticity).

property pv_flux_spectral¶: PV flux in spectral space (q·u, q·v).

property pv_spectral¶: Barotropic potential vorticity in spectral space.

property pv_zonalized¶

Zonalized PV profile on the regular latitude grid.

See Grid.zonalize().

run(model, *args, **kwargs)¶: Shortcut to BarotropicModel.run().

property stationary_wavenumber¶

Non-dimensionalised stationary (zonal) wavenumber (Ks, complex).

See diagnostics.stationary_wavenumber().

property streamfunction¶: Streamfunction of the wind.

property u¶: Zonal wind component.

property v¶: Meridional wind component.

property v_envelope_hilbert¶

Envelope of wave packets based on the Hilbert transform.

See diagnostics.envelope_hilbert().

property vo¶: Relative vorticity (alias of vorticity).

Added in version 3.1.

property vorticity¶: Relative vorticity.

State Collection¶

class barotropic.StateList(states)¶

Bases: Sequence

Immutable sequence of State instances.

Parameters:: states (iterable of State) – states to be included.

One-dimensional collection intended to represent the temporal evolution of a simulation. Provides access to all State properties and methods and a map() method for customized function application.

Added in version 3.1.

as_dataset(*args, **kwargs)¶: Shortcut to io.as_dataset()

property grid¶: The underlying Grid of all states

map(func, *args, **kwargs)¶

Apply a function to each State and collect the output.

Parameters:

func (callable) – Function to apply.
args – additional positional arguments supplied to func with every invocation.
kwargs – additional keyword argument supplied to func with every invocation.

Returns:

Sequence container with results from function applications. For special return types of func (e.g. numbers) a specialized container (e.g. numpy array) is returned.

run(model, *args, **kwargs)¶

Shortcut to BarotropicModel.run().

Parameters:

model (BarotropicModel) – the temporal integrator.
args – forwarded positional arguments.
kwargs – forwarded keyword arguments.

Returns:

2-tuple of final states (StateList) and full simulation outputs (list of StateList).