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

tojson(self)

Convert a vecter object to a json string

Returns:
    json str: A json 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

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_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

calculate_flowline_sinuosity(self)

Calculate the sinuosoty of a flowline

__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

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

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, aParameter)

Initialize the basin class object

Args:
    aParameter (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_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, 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_mesh_generation(self, iFlag_antarctic_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_analyze(self)

Analyze the domain results for every watershed

pyflowline_setup(self)

Set up the flowlinecase

pyflowline_run(self)

Run the flowlinecase simulation

Returns:
    list: A list of cell objects

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)

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