pypago.toolsec

Toolbox for the definition of gridded sections

Functions

areainsec(veci, vecj, faces, areaw, arean) Determines the area of a PAGO section given its indexes and faces
consec(veci1, vecj1, faces1, orient1, veci2, …) Function that joins multiple segments belonging to one section.
conseclr2(veci1, vecj1, faces1, orient1, …) Function that joins multiple segments belonging to one section.
correct_sections(sec, secname, offset, position) Function that allows to correct section staircases.
distance(lat1, lon1, lat2, lon2, geoid) Computes the distance between the points (lon1, lat1) and (lon2, lat2).
facesinsec(veci, vecj, dire) Function which defines the sequence of faces that allow to join two section endpoints (i.e for a segment)
lengthinsec(veci, vecj, faces, dw, dn) Determines the length of section edges depending on the cell face.
locingrid(lon, lat, matlon, matlat) Locates the nearest grid point (lon,lat) within the 2D grid defined by the matlon and matlat arrays.
make_orientation(newveci, faces, dire) Function that allows to extract the orientation of the faces, depending on which face and on the orientation of the segment
monotonous(vect) Determines whether the input array is monotonous
nodouble(veci, vecj) Function that removes the double in the veci and vecj arrays of a section.
secingrid(fromi, fromj, toi, toj) Calculates the sequence of grid points to go from (fromj, fromi) to (toj, toi), by following the straight line that joints the two end points.
areainsec(veci, vecj, faces, areaw, arean)[source]

Determines the area of a PAGO section given its indexes and faces

Parameters:
  • veci (numpy.array) – i-indexes of the section
  • vecj (numpy.array) – j-indexes of the section
  • faces (numpy.array) – array that contain the faces of the section (‘W’ or ‘N’)
  • areaW (numpy.array) – 3D-array (z, lat, lon) that contains the area of the western faces of the grid cells
  • areaN (numpy.array) – 3D-array (z, lat, lon) that contains the area of the northern faces of the grid cells
Returns:

2D (z, l) area of the PAGO section. If faces[p] == ‘N’, area[:, p] = areaN[:, vecj[l], veci[l]]

Return type:

numpy.array

consec(veci1, vecj1, faces1, orient1, veci2, vecj2, faces2, orient2)[source]

Function that joins multiple segments belonging to one section. At first does a preprocessing of the file and then calls the pypago.sec._consec._consec() function

conseclr2(veci1, vecj1, faces1, orient1, veci2, vecj2, faces2, orient2)[source]

Function that joins multiple segments belonging to one section.

correct_sections(sec, secname, offset, position)[source]

Function that allows to correct section staircases. Especially useful in order to correct sections’ junctions. It extracts the section variables (veci, vecj, etc) along the length coordinates, from offset to end or from start to offset, depending on the value of position argument.

Parameters:
  • sec (list) – section list that contains the PyPAGO objects, containing the veci, vecj, vect, … obtained from the pypago.sec.finalisesections()
  • secname (type) – section points to correct
  • offset (int) – number of points to remove
  • position (str) – {‘start’,’end’} whether we remove the first (position=’start’) or last (position=’end’) points.
distance(lat1, lon1, lat2, lon2, geoid)[source]

Computes the distance between the points (lon1, lat1) and (lon2, lat2). This function used the mpl_toolkits.basemap.pyproj.Geod.inv() function.

Parameters:
  • lat1 (float) – latitude of the first point
  • lon1 (float) – longitude of the first point
  • lat2 (float) – latitude of the second point
  • lon2 (float) – longitude of the second point
  • geoid (mpl_toolkits.basemap.pyproj.Geod) – mpl_toolkits.basemap.pyproj.Geod object used to compute the distance
Returns:

distance between the two points

Return type:

float

facesinsec(veci, vecj, dire)[source]

Function which defines the sequence of faces that allow to join two section endpoints (i.e for a segment)

By convention, we tend to favor the north and west side of each grid cell as a ‘face’ of a sequence of gridpoints.

veci and vecj are reconstructed to i) drop the points which faces are not used, and ii) double the grid points which faces are used twice.

Faces is a vector of letters:

  • N means that the north face is to be used
  • W means that the west face is to be used

Orientation is a vector of +1 or -1 that shall be applied to velocities in order to make sure that the transport is integrated in the direction dir, which is a two letter vector: NE, NW, SE or SW.

Calculation assumes that vectors are originally pointing toward N or E.

Parameters:
  • veci (numpy.array) – i index determined from pypago.sec._secingrid()
  • vecj (numpy.array) – j index determined from pypago.sec._secingrid()
  • dir (str) – orientation of the segment
Returns:

a tuple that contains the sequence of faces, i and j indexes and the orientation for each face

Return type:

tuple

Raises:
  • ValueError – if either veci or vecj are not monotonous
  • IndexError – if length of veci is 1
lengthinsec(veci, vecj, faces, dw, dn)[source]

Determines the length of section edges depending on the cell face.

Parameters:
  • veci (numpy.array) – i index of the section grid cells
  • vecj (numpy.array) – j index of the section grid cells
  • faces (numpy.array) – face of the section grid cells
  • dw (numpy.array) – scale factors on the western faces of the model cells
  • dn (numpy.array) – scale factors on the northern faces of the model cells
Returns:

length along the section

locingrid(lon, lat, matlon, matlat)[source]

Locates the nearest grid point (lon,lat) within the 2D grid defined by the matlon and matlat arrays.

Parameters:
  • lon (numpy.array) – Array that contains the longitude of the sections’ points
  • lat (numpy.array) – Array that contains the latitude of the sections’ points
  • matlon (numpy.array) – Matrix that contains the longitude of the model
  • matlon – Matrix that contains the latitude of the model
Returns:

the j and i indexes that correspond to the section endpoints on the grid

Return type:

list

make_orientation(newveci, faces, dire)[source]

Function that allows to extract the orientation of the faces, depending on which face and on the orientation of the segment

Parameters:
  • newveci (numpy.array) – array that contains the section indices (used only for recovering the size of output)
  • faces (numpy.array) – array that contains the faces of the section cells
  • dire (str) – a string that contains the orientation of the segment
monotonous(vect)[source]

Determines whether the input array is monotonous

Parameters:vect (numpy.array) – Input array
Returns:A boolean (True or False)
Return type:bool
Raises:IndexError – if length of vect is 1
>>> # monotonous
>>> vect = np.array([1, 2, 3])
>>> monotonous(vect)
True
>>> # constant
>>> vect = np.array([0, 0, 0])
>>> monotonous(vect)
True

Todo

following fail

>>> # bad input - only 1 item
>>> vect = np.array([1])
>>> monotonous(vect)
Traceback (most recent call last):
   ...
raise IndexError
nodouble(veci, vecj)[source]

Function that removes the double in the veci and vecj arrays of a section. The output list are first initialised by the first elements of the veci and vecj arrays. Then if the n-1th elements is different from the nth element, it is added to the output list

Parameters:
  • veci (numpy.array) – i indexes of the section
  • vecj (numpy.array) – j indexes of the section
Returns:

the veci and vecj indexes but with the double elements

Return type:

list

secingrid(fromi, fromj, toi, toj)[source]

Calculates the sequence of grid points to go from (fromj, fromi) to (toj, toi), by following the straight line that joints the two end points. Adjacent grid points have one side in common.

Parameters:
  • fromi (int) – start i index
  • fromj (int) – start j index
  • toi (int) – end i index
  • toj (int) – end i index