../../lib/numru/gphys/ep_flux.rb

# module NumRu::GPhys::EP_Flux in ep_flux.

## Testprogram

Test script path is 'test/test_ep_flux.rb' in expand dir of gphys.tar.gz.

## Index

- module NumRu::GPhys::EP_Flux
  - Functions:
    - ep_full_sphere
      - calculate EP Flux with full set equations on spherical coordinate.
    - div_sphere
      - calculate divergence on spherical coordinate, Not only for EP Flux!
    - strm_rmean
      - calculate residual mass stream function in spherical coordinate (it might be good precision, but enough test has not done yet.)
    - scale_height
      - get the scale height.
    - scale_height=
      - set the scale height.
    - radius
      - get the radus of planet.
    - radius=
      - set the radus of planet.
    - rot_period
      - get the rotation period of planet.
    - rot_period=
      - set the rotation period of planet.
    - g_forces
      - get the gravitational acceleration in surface.
    - g_forces=
      - set the gravitational acceleration in surface.
    - p00
      - get the reference surface pressure.
    - p00=
      - set the reference surface pressure.
    - cp
      - get the the specific heat at constant pressure of the atmosphere.
    - cp=
      - set the the specific heat at constant pressure of the atmosphere.
    - gas_const
      - get the specific heat at constant pressure of the atmosphere.
    - gas_const=
      - set the specific heat at constant pressure of the atmosphere.
    - get_constants
      - get the module variables
    - set_constants
      - set the module variables
    - make_gphys
      - convert Axis to GPhys.
    - to_w_if_omega
      - convert to velocity if gp is pressure velocity.
    - to_z_if_pressure
      - convert to altitude if gp is pressure.
    - to_p_if_altitude
      - convert to pressure if gp is altitude.
    - to_theta_if_temperature
      - convert to potential temperature of temperature if flag is true.
    - to_rad_if_deg
      - convert to radian if gp is degrees.
    - eddy_products
      - calculate eddy flux respect to dimname.
    - remove_0_at_poles
      - set value if the cos(phi) is 0 at poles (phi is latitude).
    - preparate_for_vector_on_merdional_section
      - preparate for GGraph::vector_on_merdional_section in vector_on_merdional_section.rb
  - Constants:
    - Deriv_methods
      - derivative method names.

# module NumRu::GPhys::EP_Flux

Module functions of EP_Flux Operater for GPhys.

## Functions:

`ep_full_sphere(gp_u, gp_v, gp_w_or_omega, gp_temp_or_theta, flag_temp_or_theta, xyzdims=[0,1,2])`

  Calculate Eliassen-Palm Flux(EP-Flux) from full set equations on the spherical coordinate. this method calculates EP-Flux from 4 GPhys objects, zonal-wind velocity(U), merdional-wind velocity(V), vertical-wind velocity(W) or pressure velocity(Omega), and temperature(T) or potential(Theta) temperature. check the equations on documents.

  Furthermore, Residual mean merdional circulation (0, v*, w*) can be calculated.

  ARGUMENTS

  - gp_u (GPhys): a GPhys which data is U.
  - gp_v (GPhys): a GPhys which data is V.
  - gp_w_or_omega (GPhys): a GPhys which data is W or Omega. if you give gp_omega, convert to W in this method and calculate EP-Flux.
  - gp_temp_or_theta (GPhys): a GPhys which data is T or Theta.

  - xyzdims (Array): an Array which represents location of upper gphyses's

        coordinate. if coordinate configuration is
        (longitude, latitude, z), then xyzdims = [0, 1, 2].
        else if coordinate configuration is
        (z, latitude, longitude), then xyzdims = [2, 1, 0].

  RETURN VALUE

  - epflx_y (GPhys): EP-Flux y-component. it is on the merdional hoge.
  - epflx_z (GPhys): EP-Flux z-component.
  - v_rmean (GPhys): residual zonal mean V.
  - w_rmean (GPhys): residual zonal mean W.
  - gp_lat (GPhys): latitude (its units is radian)
  - gp_z (GPhys): from vertical axis (z)
  - u_mean (GPhys): zonal-mean U.
  - theta_mean (GPhys): zonal-mean Theta.
  - uv_dash (GPhys): zonal mean of zonal-eddy products U and V.
  - vt_dash (GPhys): zonal mean of zonal-eddy products V and Theta.
  - uw_dash (GPhys): zonal mean of zonal-eddy products U and W.
  - dtheta_dz (GPhys): zonal mean Theta derivate with z.
`div_sphere(gp_y, gp_z)`

  Calculate divergence on the spherical coordinate. it is exclusive to in merdional cross section.

  ARGUMENTS

  - gp_y (GPhys): a GPhys which is merdional component you want to calculate

        divergence.

  - gp_z (GPhys): a GPhys which is vertical component you want to calculate

        divergence.

  RETURN VALUE

  - gp_div (GPhys): a GPhys which is divergence on the spherical coordinate.
`set_deriv_method( method_name )`

  Set derivative method. methods are defined in GPhys::derivative. Now cderiv and threepoint_O2nd_deriv supported

  ARGUMENTS

  - method_name (String): derivative method name.

  RETURN VALUE

  - nil
`deriv( *args )`

  Call derivative method defined in GPhys::Derivative refer to @@deriv_method.

  ARGUMENTS

  - args : Option for derivative method. Pleaase see GPhys::Derivative.

  RETURN VALUE

  - nil
`scale_height`

  return a value of the scale height on the log-pressure coordinate. default value is "7000 m".

      RETURN VALUE
      * scale height (UNumeric)

`scale_height=(h)`

  set a value of the scale height on the log-pressure coordinate.

      RETURN VALUE
      * nil

`radius`

  return a value of the radius of the planet. default value is "6.37E6 m".

      RETURN VALUE
      * radius (UNumeric)

`radius=(a)`

  set a value of the radius of the planet.

      RETURN VALUE
      * nil

`rot_period`

  return a value of the rotation period of the planet. default value is "8.64E4 s".

      RETURN VALUE
      * rotation period (UNumeric)

`rot_period=(rp)`

  set a value of the rotation period of the planet.

      RETURN VALUE
      * nil

`g_forces`

  return a value of the gravitational acceleration on the surface. default value is "9.81 m/s2".

      RETURN VALUE
      * rotation period (UNumeric)

`g_forces=(g)`

  set a value of the gravitational acceleration on the surface.

      RETURN VALUE
      * nil

`p00`

  return a value of the reference surface pressure. default value is "1.0E5 Pa".

      RETURN VALUE
      * reference surface pressure (UNumeric)

`p00=(p00)`

  set a value of the reference surface pressure.

      RETURN VALUE
      * nil

`cp`

  return a value of the specific heat at constant pressure of the atmosphere. default value is "1004.0[J.K-1.kg-1]"

      RETURN VALUE
      * reference surface pressure (UNumeric)

`cp=(cp)`

  set a value of the specific heat at constant pressure of the atmosphere.

      RETURN VALUE
      * nil

`gas_const`

  return a value of the gas constant divided by molecular mass. default value is "287.0[J.K-1.kg-1]".

      RETURN VALUE
      * reference surface pressure (UNumeric)

`gas_const=(r)`

  set a value of the gas constant divided by molecular mass.

      RETURN VALUE
      * nil

`get_constants`

  return values of the scale height, radius, rotation period, gravitational acceleration, reference surface pressure, specific heat, gas constant.

      RETURN VALUE
      * scale height (UNumeric)
      * radius (UNumeric)
      * rotation period (UNumeric)
      * gravitational acceleration (UNumeric)
      * reference surface pressure (UNumeric)
      * specific heat at constant pressure of the atmosphere (UNumeric)
      * gas constant divided by molecular mass (UNumeric)

`set_constants(scale_height, radius, rot_period, g_forces, p00, cp, gas_const)`

  set values of the scale height, radius, rotation period, and gravitational acceleration.

      ARGUMENTS
      * scale height (UNumeric)
      * radius (UNumeric)
      * rotation period (UNumeric)
      * gravitational acceleration (UNumeric)
      * reference surface pressure (UNumeric)
      * specific heat at constant pressure of the atmosphere (UNumeric)
      * gas constant divided by molecular mass (UNumeric)

      RETURN VALUE
      * nil

`make_gphys(*ax_ary)`

  make GPhys objects from Axis or VArray. data components is VArray of Axis.pos.

  ARGUMENTS

  - ax_ary (Array): an Array each objects are Axis or VArray.

  RETURN VALUE

  - gp_ary (Array): an Array each objects are GPhys.
`to_w_if_omega(gp, z)`

  convert to velocity(W) if gp is pressure velocity(Omega). decide from units gp.data.units. if it compatible with "m/s" then deem it W, else if "Pa/s" then deem it Omega.

  ARGUMENTS

  - gp(GPhys): a GPhys which data represents velocity or pressure velocity.
  - z(GPhys): a GPhys which data represents z-coordinate.

  RETURN VALUE

  - gp_w(GPhys): a GPhys which data represents velocity or pressure velocity
`to_z_if_pressure(gp)`

  convert to altitude(z) if gp is pressure coordinate (p). decide from units gp.data.units. if it compatible with "Pa" then deem it (p).

  ARGUMENTS

  - gp(GPhys): a GPhys which data represents z or pressure coordinate.

  RETURN VALUE

  - gp_z(GPhys): a GPhys which data represents z-coordinate.
`to_p_if_altitude(gp)`

  convert to pressure(p) if gp is altitude(z). decide from units gp.data.units. if it compatible with "m" then deem it (z).

  ARGUMENTS

  - gp(GPhys): a GPhys which data represents z or pressure coordinate.

  RETURN VALUE

  - gp_p(GPhys): a GPhys which data represents p-coordinate.
`to_theta_if_temperature(gp_t, z, flag_temp_or_theta=true)`

  convert gp to potential temperature(\theta) if flag_temp_or_theta is true.

  ARGUMENTS

  - gp_t(GPhys): a GPhys which data represents potential temperature or

        temperature.

  - z(GPhys) : a GPhys which data represents z-coordinate.
  - flag_temp_or_theta(True or False): a flagment if gp_t convert to.

  RETURN VALUE

  - gp_theta(GPhys): a GPhys which data represents potential temperature.
`to_rad_if_deg(gp)`

  convert to radian if gp.data.units is degrees.

  ARGUMENTS

  - gp(GPhys): a GPhys which represents angle (radian or degree).

  RETURN VALUE

  - gp_rad(GPhys): a GPhys which units is radian.
`eddy_products(gp_u, gp_v, gp_w, gp_t, dimname)`

  calculate eddy products along "dimname" dimension. now in this documents, ' means eddy from zonal mean, and () means zonal mean.

  ARGUMENTS

  - gp_u(GPhys): a GPhys which data represents zonal-wind velocity(m/s).
  - gp_v(GPhys): a GPhys which data represents merdional-wind velocity(m/s).
  - gp_w(GPhys): a GPhys which data represents vertical-wind velocity(m/s).
  - gp_t(GPhys): a GPhys which data represents temperature(K).

  RETURN VALUE

  - uv_dash(GPhys): a GPhys which represents (gp_u'*gp_v').
  - vt_dash(GPhys): a GPhys which represents (gp_v'*gp_t').
  - uw_dash(GPhys): a GPhys which represents (gp_u'*gp_w').
`remove_0_at_poles(cos_gp)`

  set value if the cos(latitude) is nearly equal to 0 (|x|< 1e-6) at poles. at North pole, new value is 2 and at South pole 2

      ARGUMENTS
      * cos_gp(GPhys): a GPhys which represents latitude.

      RETURN VALUE
      * new_cos_gp(GPhys): a GPhys which value at poles displaceed.

`preparate_for_vector_on_merdional_section(xax, yax)`

  preparate for GGraph::vector_on_merdional_section in vector_on_merdional_section.

  1. check yax if it is proportional to p
  2. get axis ( a*phi, z )

      ARGUMENTS
      * xax(VArray): a VArray which represents x axis.
      * yax(VArray): a VArray which represents y axis.

      RETURN VALUE
      * va_aphi(VArray): a VArray which represents x-coordinate(radius * phi).
      * va_z(VArray): a VArray which represents z-coordinate.
      * was_proportional_to_p(True or False): flag original axis proportional to
                                              pressure or z.

`strm_rmean(v_rmean, yzdims=[0,1])`

  Calculate mass stream function for residual zonal mean circulation.

  ARGUMENTS

  - v_rmean (GPhys): a GPhys which is residual zonal mean V.
  - yzdims (Array): an Array which represents axis.

  RETURN VALUE

  - gp_strm (GPhys): a GPhys which is mass stream function on merdional section.

## Constants:

`Deriv_methods`

  derivative method name [ 'cderiv', 'threepoint_O2nd_deriv' ]