Documentation

Generates a CrossSectionInputFile for FM2PROF from an existing 1D network.

A CrossSectionInputFile is a file that contains the locations of cross-sections as X,Y coordinates, the lengths of each cross-section and the branch and offset/chainage on which they are located. For a conceptual overview of how this data is used in FM2PROF, see Control Volumes.

This is a vitally important file for FM2PROF, as it defines not only where the cross-sections are located, but also how 2D volumes are mapped to 1D widths. This utility helps to generate a valid and consistent input file. Manual editing of this file is only recommended for advanced users.

Cross-Section Placement

By default, cross-sections are placed at all computational points in the 1D network. However, this can lead to cross-sections in places where they are not desired. See Troubleshooting for examples of how to diagnose such issues.

To customise the placement of cross-sections, it supports an optional Branch Rule File (see below).

Example usage

Example

This illustrates how to use the tool in Python code:

from fm2prof.utils import GenerateCrossSectionLocationFile

input = {
     "network_definition_file": "NetworkDefinitionFile.ini",
     "cross_section_location_file": "CrossSectionLocationFile.ini",
     "branch_rule_file": "BranchRuleFile.ini"
}
GenerateCrossSectionLocationFile(**input)

Branch Rule File

This optional file is used to exclude certain computational points from being used as the location of a cross-section. This is particularly useful when smaller branches connect to a major branch, see Troubleshooting.

The branch_rule_file is a comma-separated file with the following syntax:

    branch,rules,exclusions

Rules

Rules are general rules to exclude cross-sections. Supported general rules are:

• onlyFirst: only keep the first cross-section, and exclude all others
• onlyLast: only keep the last cross-section, and exclude all others
• onlyEdges: only keep the first and last cross-section, and exclude all others
• ignoreFirst: exclude the first cross-section on a branch
• ignoreLast: exclude the last cross-section on a branch
• ignoreEdges: exclude the first and last cross-section on a branch
• noRule: use to not use any of the above rules

Exclusions

Exclusions are used to exclude specific cross-sections by id.

Usage

To only exclude one specific cross-section:

    Channel1, noRule, channel_1_350.000

In this case, the computational point with name channel_1_350.000 will not be used as the location of a cross-section, but all other computational points on branch Channel1 will be used.

Rules and individual exclusions can be mixed, e.g.:

    Channel1, ignoreLast, channel_1_350.000

More than one exclusion can be specified, e.g.:

    Channel1, ignoreLast, channel_1_350.000, channel_1_400.000

Generate cross section location file object.

Parameters:

Name	Type	Description	Default
network_definition_file	str | Path	network definition file	required
cross_section_location_file	str | Path	cross-section location file	required
branch_rule_file	str | Path	branch rule file. Defaults to "".	''

Source code in fm2prof\utils.py

def __init__(
    self,
    network_definition_file: str | Path,
    cross_section_location_file: str | Path,
    branch_rule_file: str | Path = "",
) -> None:
    """Generate cross section location file object.

    Args:
        network_definition_file (str | Path): network definition file
        cross_section_location_file (str | Path): cross-section location file
        branch_rule_file (str | Path, optional): branch rule file. Defaults to "".

    """
    super().__init__()

    network_definition_file, cross_section_location_file, branch_rule_file = map(
        Path,
        [network_definition_file, cross_section_location_file, branch_rule_file],
    )

    if not network_definition_file.exists():
        err_msg = "Network difinition file not found"
        raise FileNotFoundError(err_msg)

    self._network_definition_file_to_input(network_definition_file, cross_section_location_file, branch_rule_file)