mesh2scattering.numcalc#

Contains functions for managing numerical calculations.

Functions:

build_or_fetch_numcalc([replace_existing])

Get the numcalc executable from building (linux and mac) or downloading the exe from Github (windows) and will be placed in the numcalc/bin folder.

calc_and_read_ram(project_path, ...)

Calculate if not exists and returns the memory usage.

manage_numcalc([project_path, numcalc_path, ...])

Run NumCalc on one or multiple NumCalc project folders.

read_ram_estimates(folder)

Read estimated RAM consumption from Memory.txt.

remove_outputs(paths[, boundary, grid, log])

Remove output data from scattering project folder.
mesh2scattering.numcalc.build_or_fetch_numcalc(replace_existing=False)[source]#

Get the numcalc executable from building (linux and mac) or downloading the exe from Github (windows) and will be placed in the numcalc/bin folder.

Building NumCalc on Linux requires the build-essential package to be installed. On Ubuntu, this can be done with the following command:

sudo apt-get install build-essential

For Mac, the xcode command line tools are required.

Parameters:

replace_existing (bool, optional) – If True, the existing NumCalc executable is replaced. The default is False.

Returns:

NumCalc path

Return type:

str

mesh2scattering.numcalc.calc_and_read_ram(project_path, numcalc_executable)[source]#

Calculate if not exists and returns the memory usage.

Parameters:

  • project_path (str, path) – project root path.

  • numcalc_executable (str, path) – Path to numcalc executable, on Windows it ends with NumCalc.exe and on Unix system NumCalc

Returns:

ram –

with shape (N, 3), where the first row definitions are as follows:

  • id of the frequency

  • frequency itself

  • expected RAM usage in GB

Return type:

numpy.ndarray

mesh2scattering.numcalc.manage_numcalc(project_path=None, numcalc_path=None, max_ram_load=None, ram_safety_factor=1.05, max_cpu_load=90, max_instances=None, wait_time=15, starting_order='alternate', confirm_errors=False)[source]#

Run NumCalc on one or multiple NumCalc project folders.

This script monitors the RAM and CPU usage and starts a new NumCalc instance whenever enough resources are available. The required RAM for each frequency step is estimated using NumCalc’s estimate_ram option. A log file is written to the project_path containing detailed information on the launched frequency steps, available resources, and detected errors.

Note

manage_numcalc can also be launched by running the python script manage_numcalc_script.py contained in the subfolder mesh2scattering/NumCalc of the mesh2scattering Git repository.

Parameters:

  • project_path (str, optional) – The directory to simulate: It can be path to either 1- directory that contains multiple NumCalc project folders or 2- one NumCalc project folder (folder containing “parameters.json”). The default None uses os.getcwd()

  • numcalc_path (str, optional) – This is the path to the NumCalc binary (by default ‘NumCalc’ is used). By default, build_or_fetch_numcalc is used.

  • max_ram_load (number, optional) – The RAM that can maximally be used in GB. New NumCalc instances are only started if enough RAM is available. The default None uses all available RAM.

  • ram_safety_factor (number, optional) – A safety factor that is applied to the estimated RAM consumption. The estimate is obtained using NumCalc -estimate_ram. The default of 1.05 would for example assume that 10.5 GB ram are needed if a RAM consumption of 10 GB was estimated by NumCalc.

  • max_cpu_load (number, optional) – Maximum allowed CPU load in percent. New instances are only launched if the current CPU load is below this value. The default is 90 percent.

  • max_instances (int, optional) – The maximum numbers of parallel NumCalc instances. If max_instances is None, by default a new instance is launched until the number of available CPU cores given by psutil.cpu_count() is reached.

  • wait_time (int, optional) – Delay in seconds for waiting until the RAM and CPU usage is checked after launching a NumCalc instance. This has to be sufficiently large for the RAM and CPU to be fully used by the started NumCalc instance. The default is 15 s but values of 60 s or even more might be required depending on the machine. The RAM values that manage_numcalc outputs are usually a good indicator to check if wait_time is sufficiently high. After this initial wait time, the resources are checked every second. And the next instance is started, once enough resources are available.

  • starting_order (str, optional) –

    Control the order in which the frequency steps are launched.

    'high'

    Always launches the step with the highest possible memory consumption.

    'low'

    Always launches the step with the lowest estimated memory consumption

    'alternate' (default)

    mixes the two approaches above.

  • confirm_errors (bool, optional) – If True, manage_numcalc waits for user input in case an error ” occurs. The default false exits the function immediately if an error occurs.

mesh2scattering.numcalc.read_ram_estimates(folder: str)[source]#

Read estimated RAM consumption from Memory.txt.

Note that the RAM consumption per frequency step can be estimated and written to Memory.txt by calling NumCalc -estimate_ram. This must be done before calling this function.

Parameters:

folder (str) – full path to the source folder containing the Memory.txt file from which the estimates are read

Returns:

estimates – An array of shape (N, 3) where N is the number of frequency steps. The first column contains the frequency step, the second the frequency in Hz, and the third the estimated RAM consumption in GB.

Return type:

numpy array

mesh2scattering.numcalc.remove_outputs(paths, boundary=False, grid=False, log=False)[source]#

Remove output data from scattering project folder.

Use this function to delete output that is no longer needed and is taking too much disk space.

Parameters:

  • paths (str, tuple of strings) – Paths under which scattering project folders are searched. Can contain * remove data from multiple project folders, e.g., path/*left will remove data from all folders in path that end with left.

  • boundary (bool, optional) – Remove raw pressure and velocity simulated on the boundary, i.e., the mesh. This data is saved in project_folder/NumCalc/source_*/be.out/be.*/*Boundary

  • grid (bool, optional) – Remove raw pressure and velocity simulated on the evaluation grid.This data is saved in project_folder/NumCalc/source_*/be.out/be.*/*EvalGrid

  • log (bool, optional) – Remove log (*.txt, *.out) files in source_* dir.