Convergence Analysis

Find more background information on hydro-informatics.com.

Usage Example

Minimal

from pythomac import extract_fluxes


simulation_dir = "/home/telemac-user/simulations/rhine/"
cas_name = "steady2d.cas"
extract_fluxes(simulation_dir, cas_name, plotting=False)

Full application

"""
This script features an example for flux extraction and convergence analysis with pythomac. It requires that a
    simulation ran with ``telemac2d.py steady2d.cas -s`` and that the .cas file contained the keyword
    ``PRINTING CUMULATED FLOWRATES : YES``.

@author: Sebastian Schwindt
@year: 2023

Usage:
    This script should be placed relative to a Telemac simulation as follows:
        + Simulation: HOME/hytelemac/steady2d-tutorial/steady2d.cas
        + This script: HOME/postpro/example_flux_convergence.py
        + To change this behavior, modify the variable simulation_dir

Example:
    Visit https://hydro-informatics.com/numerics/telemac/convergence.html

"""
import os
from pathlib import Path
from pythomac import extract_fluxes, calculate_convergence, get_convergence_time

# set directories and define steering (cas) file name
simulation_dir = str(Path(__file__).parents[1]) + "{0}hytelemac{0}steady2d-tutorial".format(os.sep)
telemac_cas = "steady2d-conv.cas"
print(simulation_dir)

# extract fluxes across boundaries
fluxes_df = extract_fluxes(
    model_directory=simulation_dir,
    cas_name=telemac_cas,
    plotting=True
)

# back-calculate Telemac timestep size
timestep_in_cas = int(max(fluxes_df.index.values) / (len(fluxes_df.index.values) - 1))

# plot convergence
iota_t = calculate_convergence(
    series_1=fluxes_df["Fluxes Boundary 1"][1:],  # remove first zero-entry
    series_2=fluxes_df["Fluxes Boundary 2"][1:],  # remove first zero-entry
    cas_timestep=timestep_in_cas,
    plot_dir=simulation_dir
)

# write the result to a CSV file
iota_t.to_csv(os.path.join(simulation_dir, "convergence-rate.csv"))

# identify the timestep at which convergence was reached at a desired precision
convergence_time_iteration = get_convergence_time(
    convergence_rate=iota_t["Convergence rate"],
    convergence_precision=1.0E-6
)

if not("nan" in str(convergence_time_iteration).lower()):
    print("The simulation converged after {0} simulation seconds ({1}th printout).".format(
        str(timestep_in_cas * convergence_time_iteration), str(convergence_time_iteration)))

Script and Function docs

Flux Analyst

Extract data from a Telemac simulation that has already been running. The codes are inspired by the following jupyter notebook:

HOMETEL/notebooks/data_manip/extraction/output_file_extraction.ipynb

which uses the following example case:

/examples/telemac2d/bump/t2d_bump_FE.cas

@author: Sebastian Schwindt (July 2023)

pythomac.flux_analyst.calculate_convergence(series_1, series_2, conv_constant=1.0, cas_timestep=1, plot_dir=None)

Approximate convergence according to

https://hydro-informatics.com/numerics/telemac/convergence.html#tm-calculate-convergence

Parameters:

• series_1 (list or np.array) – series_1 should converge toward series_2 (both must have the same length)

• series_2 (list or np.array) – series_2 should converge toward series_1 (both must have the same length)

• conv_constant (float) – a convergence constant to reach (default is 1.0)

• cas_timestep (int) – the timestep defined in the cas file

• plot_dir (str) – if a directory is provided, a convergence plot will be saved here

Return pandas.DataFrame:

with one column, notably the convergence_rate iota as np.array

pythomac.flux_analyst.extract_fluxes(model_directory='', cas_name='steady2d.cas', plotting=True)

This function writes a .csv file and an x-y plot of fluxes across the boundaries of a Telemac2d model. It auto-

matically place the .csv and .png plot files into the simulation directory (i.e., where the .cas file is).

Notes

• The Telemac simulation must have been running with the ‘-s’ flag (telemac2d.py my.cas -s).

• Make sure to activate the .cas keyword PRINTING CUMULATED FLOWRATES : YES

• This script skips volume errors (search tags are not implemented).

• Read more about this script at

  https://hydro-informatics.com/numerics/telemac/telemac2d-steady.html#verify-steady-tm2d

Parameters:

• model_directory (str) – the file directory where the simulation lives

• cas_name (str) – name of the .cas steering file (without directory)

• plotting (bool) – default (True) will place a figure called flux-convergence.png in the simulation directory

Return pandas.DataFrame:

time series of fluxes across boundaries (if Error int: -1)

pythomac.flux_analyst.get_convergence_time(convergence_rate, convergence_precision=0.0001)

Calculate at which simulation time the simulation converged at a desired level of

convergence precision

Parameters:

• convergence_rate (numpy.array) – iota calculated with calculate_convergence

• convergence_precision (float) – define the desired level of convergence precision

Return numpy.int64:

the time iteration number

Plotting

Plot functions based on matplotlib

pythomac.utils.plots.plot_df(df, file_name, x_label=None, y_label=None, column_keyword='', legend=True)

Plot a pandas DataFrame as lines with markers. The dataframe index is used for the x-axis. The function can handle a maximum of twelve columns

Parameters:

• df (pandas.DataFrame) – index serves for x-axis, columns containing a particular keyword are plotted on the y-axis (make sure these columns have the same units)

• file_name (str) – full path and name of the plot to be created

• x_label (str) – label for the x-axis

• y_label (str) – label for the y-axis

• column_keyword (str) – define a keyword that columns must contain to be plotted. The default ‘’ (empty string) plots all columns.

• legend (bool) – place a legend (default is True).

Returns: