14. API Reference

14.1. Class

14.1.1. Basic elements

pyflowline.classes.vertex.pyvertex : public object

The vertex class

Args:
    object (_type_): None

Returns:
    pyvertex: A vertex object

Public Functions

__init__(self, aParameter)

Initilize a vertex object

Args:
    aParameter (dict): A dictionary parameters

toNvector(self)

Note: replicated in LatLon_NvectorEllipsoidal

Returns:
    pynvector: A nvector object

__eq__(self, other)

Check whether two vertices are equivalent

Args:
    other (pyvertex): The other vertex

Returns:
    int: 1 if equivalent, 0 if not

__ne__(self, other)

Check whether two vertices are equivalent

Args:
    other (pyvertex): The other vertex

Returns:
    int: 0 if equivalent, 1 if not

calculate_distance(self, other)

Calculate the distance between two vertices

Args:
    other (pyvertex): The other vertex

Returns:
    float: The great circle distance

calculate_xyz(self)

Calculate the x, y, z based on dLongitude and dLatitude

Returns:
    tuple: The x, y, z

tojson(self)

Convert a vecter object to a json string

Returns:
    json str: A json string

towkt(self)

Convert a vertex object to a WKT string

Returns:
    str: A WKT string

pyflowline.classes.edge.pyedge : public object

The pyedge class

Args:
    object (object): None

Returns:
    pyedge: A edge object

Public Functions

__init__(self, pVertex_start_in, pVertex_end_in)

Initilize a pyedge object

Args:
    pVertex_start_in (pyvertex): The starting vertex
    pVertex_end_in (pyvertex): The ending vertex

create(cls, pVertex_start_in, pVertex_end_in)

Factory method to create a pyedge object

Args:
    pVertex_start_in (pyvertex): The starting vertex
    pVertex_end_in (pyvertex): The ending vertex

Returns:
    pyedge or None: A pyedge object if valid, otherwise None

calculate_length(self)

Calcualate the length of the edge

Returns:
    float: The length of the edge

check_shared_vertex(self, other)

Check whether two edges are sharing the same vertex

Args:
    other (pyedge): The other edge object to be checked

Returns:
    int: Flag, 1: shared; 0: non-sharing

check_upstream(self, other)

Check whether another edge is the upstream of current edge

Args:
    other (pyedge): The other edge object to be checked

Returns:
    int: Flag, 1: upstream; 0: non-upstream

check_downstream(self, other)

Check whether another edge is the downstream of current edge


Args:
    other (pyedge): The other edge object to be checked

Returns:
    int: Flag, 1: downstream; 0: non-downstream

split_by_length(self, dLength_in)

Split an edge using the threshold

Args:
    dLength_in (float): The length threshold

Returns:
    list [pyedge]: A list of edge objects, length of 1 if it meets the requirement

reverse(self)

Reverse an edge

is_overlap(self, pEdge_in)

Check if two edges overlap each other

Args:
    pEdge_in (pyedge): The other edge to be checked

Returns:
    int: 1 if overlap; 0 if not

check_vertex_on_edge(self, pVertex_in)

Check if a vertex on an edge

Args:
    pVertex_in (pyvertex): The vertex to be checked

Returns:
    tuple[int, float, float]: 1 if it is on; 0 if not. Length and distance are calculated if on.

__eq__(self, other)

Check if two edges are equivalent

Args:
    other (pyedge): The other edge
    how about direction?

Returns:
    int: 1 if equivalent; 0 if not

__ne__(self, other)

Check if two edges are equivalent

Args:
    other (pyedge): The other edge

Returns:
    int: 0 if equivalent; 1 if not

tojson(self)

Convert an edge object to a json string

Returns:
    json str: A json string

pyflowline.classes.flowline.pyflowline : public object

The pyflowline class

Args:
    object (object): None

Returns:
    pyflowline: The flowline object

Public Functions

__init__(self, aEdge)

Initilize a flowline object

Args:
    aEdge (list [pyedge]): A list of edge objects

calculate_length(self)

Calcualte the length

Returns:
    float: The length of the flowline

check_upstream(self, other)

Check whether another flowline is upstream or not

Args:
    other (pyflowline): The other flowline

Returns:
    int: 1 if it is, 0 if not

check_downstream(self, other)

Check whether another flowline is downstream or not

Args:
    other (pyflowline): The other flowline

Returns:
    int: 1 if it is, 0 if not

reverse(self)

Reverse a flowline

merge_upstream(self, other)

Merge two flowlines as one

Args:
    other (pyflowline): The other flowline

Returns:
    pyflowline: The merged flowline

split_edge_by_length(self, dDistance)

Split a flowline using the length threshold

Args:
    dDistance (float): The length threshold for each edge

Returns:
    pyflowline: The updated flowline

copy_attributes(self, other)

Copy the attributes from another flowline

Args:
    other (pyflowline): The other flowline

calculate_flowline_sinuosity(self)

Calculate the sinuosoty of a flowline

calculate_buffer_zone_polygon(self, dRadius, sFilename_out=None, sFolder_out=None)

Calculate the buffer zone polygon

Args:
    dRadius (float): The buffer zone distance

Returns:
    list: A list of buffer zone points

__eq__(self, other)

Check whether two flowline are equivalent

Args:
    other (pyflowline): The other flowline

Returns:
    int: 1 if equivalent, 0 if not

__ne__(self, other)

Check whether two flowline are equivalent

Args:
    other (pyflowline): The other flowline

Returns:
    int: 0 if equivalent, 1 if not

tojson(self)

Convert a pyflowline object to a json string

Returns:
    json str: A json string

towkt(self)

Convert a pyflowline object to a wkt string

Returns:
    str: A wkt string

update_wkt(self)

Update the wkt string of the flowline

14.1.2. Mesh cell

pyflowline.classes.hexagon.pyhexagon : public pyflowline.classes.cell.pycell

The hexagon cell class

Args:
    pycell (obj): None

Returns:
    pyhexagon: A hexagon object

Public Functions

__init__(self, dLon, dLat, aEdge, aVertex)

Initilize a hexagon cell object

Args:
    dLon (float): The longitude of center
    dLat (float): The latitude of center
    aEdge (list [pyedge]): A list of edges that define the hexagon
    aVertex (list [pyvertex]): A list of vertices the define the hexagon

has_this_edge(self, pEdge_in)

Check whether the hexagon contains an edge

Args:
    pEdge_in (pyedge): The edge to be checked

Returns:
    int: 1 if found, 0 if not

which_edge_cross_this_vertex(self, pVertex_in)

Find which edge overlap with a vertex

Args:
    pVertex_in (pyvertex): The vertex to be checked

Returns:
    tuple [int, pyedge]: 1 if found, with the edge object; 0 if not found

calculate_cell_area(self)

Calculate the area of the hexagon cell

Returns:
    float: The area in m2

calculate_edge_length(self)

Calculate the effective length of the hexagon cell

Returns:
    float: The effective length

share_edge(self, other)

Check whether a hexagon shares an edge with another hexagon

Args:
    other (pyhexagon): The other hexagon

Returns:
    int: 1 if share, 0 if not

tojson(self)

Convert a hexagon object to a json string

Returns:
    json str: A json string

pyflowline.classes.square.pysquare : public pyflowline.classes.cell.pycell

The square cell class

Args:
    pycell (_type_): None

Returns:
    pysquare: A square cell object

Public Functions

__init__(self, dLon, dLat, aEdge, aVertex)

Initilize a square cell object

Args:
    dLon (float): The longitude of center
    dLat (float): The latitude of center
    aEdge (list [pyedge]): A list of edges that define the square cell
    aVertex (list [pyvertex]): A list of vertices the define the square cell

has_this_edge(self, pEdge_in)

Check whether the square contains an edge

Args:
    pEdge_in (pyedge): The edge to be checked

Returns:
    int: 1 if found, 0 if not

which_edge_cross_this_vertex(self, pVertex_in)

Find which edge overlap with a vertex

Args:
    pVertex_in (pyvertex): The vertex to be checked

Returns:
    tuple [int, pyedge]: 1 if found, with the edge object; 0 if not found

calculate_cell_area(self)

Calculate the area of the hexagon cell

Returns:
    float: The area in m2

calculate_edge_length(self)

Calculate the effective length of the square cell

Returns:
    float: The effective length

share_edge(self, other)

Check whether a square cell shares an edge with another cell

Args:
    other (pysquare): The other cell

Returns:
    int: 1 if share, 0 if not

tojson(self)

Convert a square object to a json string

Returns:
    json str: A json string

pyflowline.classes.latlon.pylatlon : public pyflowline.classes.cell.pycell

The latlon cell class

Args:
    pycell (obj): None

Returns:
    pylatlon: A latlon cell object

Public Functions

__init__(self, dLon, dLat, aEdge, aVertex)

Initilize a latlon cell object

Args:
    dLon (float): The longitude of center
    dLat (float): The latitude of center
    aEdge (list [pyedge]): A list of edges that define the latlon cell
    aVertex (list [pyvertex]): A list of vertices the define the latlon

has_this_edge(self, pEdge_in)

Check whether the latlon contains an edge

Args:
    pEdge_in (pyedge): The edge to be checked

Returns:
    int: 1 if found, 0 if not

which_edge_cross_this_vertex(self, pVertex_in)

Find which edge overlap with a vertex

Args:
    pVertex_in (pyvertex): The vertex to be checked

Returns:
    tuple [int, pyedge]: 1 if found, with the edge object; 0 if not found

calculate_cell_area(self)

Calculate the area of the latlon cell

Returns:
    float: The area in m2

calculate_edge_length(self)

Calculate the effective length of the latlon cell

Returns:
    float: The effective length

share_edge(self, other)

Check whether a latlon shares an edge with another latlon

Args:
    other (pylatlon): The other latlon cell

Returns:
    int: 1 if share, 0 if not

tojson(self)

Convert a latlon object to a json string

Returns:
    json str: A json string

pyflowline.classes.mpas.pympas : public pyflowline.classes.cell.pycell

The MPAS cell class

Args:
    pycell (object): None

Returns:
    pympas: A mpas cell object

Public Functions

__init__(self, dLon, dLat, aEdge, aVertex)

Initilize a mpas cell object

Args:
    dLon (float): The longitude of center
    dLat (float): The latitude of center
    aEdge (list [pyedge]): A list of edges that define the hexagon
    aVertex (list [pyvertex]): A list of vertices the define the hexagon

calculate_cell_bound(self)

Calculate the bounding box of a cell,
this method may need to consider whether a mesh cell crosses the international date line
this method should also be used for the rtree index
this method should also be used by other unstructured mesh cells, such as dggrid?

has_this_edge(self, pEdge_in)

Check whether the cell contains an edge

Args:
    pEdge_in (pyedge): the to be checked edge

Returns:
    int: 1 if contains; or else 0

which_edge_cross_this_vertex(self, pVertex_in)

When a flowline intersects with a cell, this function finds out which edge is intersected

Args:
    pVertex_in (pyvertex): the intersected vertex

Returns:
    tuple: (1, edge) if contains; or else (0, None)

calculate_cell_area(self)

Calculate the area of a cell, this function is not used for mpas cell

Returns:
    float: cell area

calculate_edge_length(self)

Calculate the effective cell length/resolution

Returns:
    float: effective cell length/resolution

share_edge(self, other)

Check if two cells share an edge

Args:
    other (pympas): the other cell

Returns:
    int: 1 if shared, 0 if not

tojson(self)

Convert a cell into a json string

Returns:
    json str: A json string

14.1.3. Others

pyflowline.classes.basin.pybasin : public object

Basin class

Args:
    (object): None

Returns:
    None: A basin object

Public Functions

__init__(self, aConfig_in, iFlag_create_directory_in=1)

Initialize the basin class object

Args:
    aConfig_in (dict): Dictionary for parameters

basin_flowline_simplification(self)

Run the basin flowline simplification

Returns:
    list [pyflowline]: A list of simplified flowline

basin_reconstruct_topological_relationship(self, iMesh_type, sFilename_mesh)

Run the basin topologic relationship reconstruction

Args:
    iMesh_type (int): Mesh type
    sFilename_mesh (str): Filename of the geojson mesh

Returns:
    list [pyflowline]: A list of intersected cells

basin_build_confluence(self, aFlowline_basin_in, aVertex_confluence_in)

Build the conflence

Args:
    aFlowline_basin_in (list [pyflowline]): A list of flowlines in this basin
    aVertex_confluence_in (list [pyconfluence]): A list of vertices in this basin

Returns:
    list [pyconfluence]: A list of confluences in this basin

basin_analyze(self)

Analyze the basin results including length, sinuosity, and breaching angle

basin_export(self)

Export the basin outputs in json format

basin_export_flowline(self, aFlowline_in, sFilename_json_in, iFlag_projected_in=None, pSpatial_reference_in=None)

Export the basin flowline to geojson

Args:
    aFlowline_in (list [pyflowline]): A list of flowlines
    sFilename_json_in (str): The output json filename
    iFlag_projected_in (int, optional): Flag if re-projection is needed. Defaults to None.
    pSpatial_reference_in (object, optional): The spatial reference if re-projection is needed. Defaults to None.

basin_export_basin_info_to_json(self)

Export the basin basin object to json

basin_export_flowline_info_to_json(self)

Export the flowline object to json

basin_export_confluence_info_to_json(self)

Export the confluence object to json

tojson(self)

Export the basin object to json

Returns:
    json str: A json string

basin_export_config_to_json(self, sFilename_output_in=None)

Export the basin object to json using the encoder

Args:
    sFilename_output_in (str, optional): The json filename. Defaults to None.

basin_convert_flowline_to_geojson(self)

Convert the flowline to geojson

basin_convert_watershed_boundary_to_geojson(self)

Convert the boundary to geojson

basin_calculate_flowline_length(self, aFlowline_in)

Calculate the length of flowlines

Args:
    aFlowline_in (list [pyflowline]): A list of flowlines

Returns:
    float: The total length of all flowlines

basin_calculate_river_sinuosity(self)

Calcualte the the river sinuosity

basin_calculate_confluence_branching_angle(self)

Calcualte the the river confluence branching angle

basin_evaluate(self, iMesh_type, sMesh_type)

Evaluate the model performance

Args:
    iMesh_type (int): The mesh type
    sMesh_type (str): The mesh type

basin_evaluate_area_of_difference(self, iMesh_type, sMesh_type)

Evaluate the model performance using area of difference

Args:
    iMesh_type (int): The mesh type
    sMesh_type (str): The mesh type

pyflowline.classes.pycase.flowlinecase : public object

The flowline case class

Args:
    object (obj): None

Returns:
    flowlinecase: A flowlinecase object

Public Functions

__init__(self, aConfig_in, iFlag_standalone_in=None, iFlag_create_directory_in=1, sModel_in=None, sDate_in=None, sWorkspace_output_in=None)

Initialize a flowlinecase object

Args:
    aConfig_in (dict): A dictionary of parameters
    iFlag_standalone_in (int, optional): Flag for whether run the case standalone. Defaults to None.
    sModel_in (str, optional): The model name. Defaults to None.
    sDate_in (str, optional): The case date. Defaults to None.
    sWorkspace_output_in (str, optional): The output workspace. Defaults to None.

pyflowline_setup(self)

Set up the flowlinecase

pyflowline_mesh_generation(self, iFlag_antarctic_in=None, iFlag_arctic_in=None)

The mesh generation operation

Returns:
    list [pycell]: A list of cell object

pyflowline_reconstruct_topological_relationship(self)

The topological relationship reconstruction operation

Args:
    aCell_raw (list [pycell]): A list of intersected cell objects

Returns:
    tuple [list [pycell], list [pyflowline], list [long]]: A list of cells, flowlines, and outlet cell IDs.

pyflowline_merge_cell_info(self, aCell_raw)

Merge cell information after reconstruction

Args:
    aCell_raw (list [pycell]): The original cell information that contains neighbor definition
    This information is defined in the mesh generation function, so mesh generation must be run.

Returns:
    list [pycell]: The updated list of cell objects.

pyflowline_run(self)

Run the flowlinecase simulation

Returns:
    list: A list of cell objects

pyflowline_burn_watershed_boundary(self)

Burn the watershed boundary into the mesh

pyflowline_analyze(self)

Analyze the domain results for every watershed

pyflowline_evaluate(self)

Evaluate the model performance

pyflowline_export(self)

Export the model outputs

pyflowline_export_mesh_info_to_json(self)

Export the mesh information to a json file

tojson(self)

Convert the flowline case object to a json string

Returns:
    json str: A json string

pyflowline_print(self)

Print the flowline case object

pyflowline_export_config_to_json(self, sFilename_output_in=None, iFlag_export_basin_in=1)

Export the configuration to a json file

Args:
    sFilename_output_in (str, optional): The json filename. Defaults to None.

pyflowline_export_basin_config_to_json(self, sFilename_output_in=None)

Export the member basin configuration to a json file

Args:
    sFilename_output_in (str, optional): The json filename. Defaults to None.

class pyconfluence

The pyconfluence class
Returns:
    object: A confluence object

Public Functions

__init__(self, pVertex_center, aFlowline_upstream_in, pFlowline_downstream_in)

Initialize a pyconfluence object

Args:
    pVertex_center (pyvertex): The center vertex
    aFlowline_upstream_in (list [pyflowline]): A list of upstream flowlines
    pFlowline_downstream_in (pyflowline): The downstream flowline

calculate_branching_angle(self)

Calcualte the confluence branching angle (https://www.pnas.org/doi/10.1073/pnas.1215218109)

Returns:
    float: The branching angle in degree

tojson(self)

Convert a pyconfluence object to json

Returns:
    json str: A json string

pyflowline.classes.link.pycelllink : public object

The cell link class

Args:
    object (obj): None

Returns:
    pycelllink: A link object

Public Functions

__init__(self, pCell_start_in, pCell_end_in, pEdge_link_in)

Initilize a link object

Args:
    pCell_start_in (pycell): The starting cell object
    pCell_end_in (pycell): The ending cell object
    pEdge_link_in (pyedge): An edge object that links two cells

tojson(self)

Convert a cell link object to a json string

Returns:
    json str: A json string