Constant Variables

The variables defined here are used globally in the code. If these variables are modified, the code behaves differently.

The following variables are the default coordinate names in Antares. If a variable name is included in KNOWN_COORDINATES, then the variable will be considered as a mesh coordinate, except otherwise stated in a specific file reader.

Constants.KNOWN_COORDINATES = [['x', 'y', 'z'], ['x', 'y', 'Z'], ['x', 'Y', 'z'], ['x', 'Y', 'Z'], ['X', 'y', 'z'], ['X', 'y', 'Z'], ['X', 'Y', 'z'], ['X', 'Y', 'Z'], ['CoordinateX', 'CoordinateY', 'CoordinateZ']]
Constants.LOCATIONS = ['node', 'cell']

Global Variables

Coordinates

GlobalVar.coordinates = ['x', 'y', 'z']

This variable defines the default coordinate names. The first coordinate is, by default, the rotation axis (when needed).

This variable can be modified explicitely with the following function.

antares.core.GlobalVar.set_default_name(var, value)

Set default variable name to value.

Parameters:

  • var (str in [‘coordinates’, ‘base’, ‘zone’, ‘instant’]) – variable name.

  • value (list(str), or str) – new default name.

GlobalVar.cartesian_coordinates = ['x', 'y', 'z']

This variable defines the default cartesian coordinate names (same as GlobalVar.coordinates).

GlobalVar.cylindrical_coordinates = ['x', 'r', 'theta']

This variable defines the default cylindrical coordinate names.

This variable can be modified explicitely with the following function.

antares.core.GlobalVar.set_default_cylindrical_coordinates(coord_names)

Set default GlobalVar.cylindrical_coordinates to coord_names.

Parameters:

coord_names (list(str)) – new default names of coordinates.

Default names

GlobalVar.base_name = '0000'
GlobalVar.zone_name = '0000'
GlobalVar.instant_name = '0000'

These variables can be modified explicitely with the following function.

antares.core.GlobalVar.set_default_name(var, value)

Set default variable name to value.

Parameters:

  • var (str in [‘coordinates’, ‘base’, ‘zone’, ‘instant’]) – variable name.

  • value (list(str), or str) – new default name.

FILES_CACHED

This singleton manages the file cache system to reduce read operations in some situations. It is not exposed to the antares user interface yet.

OpenFilesCache.FILES_CACHED = None

This variable can be modified explicitely with the following function.

antares.io.OpenFilesCache.set_open_files_cache(enable, nb_max_open_files=10)

Set the status of the global module variable FILES_CACHED.

Parameters:

  • enable (bool) – True if the cache should be enabled, False if the cache should be disabled.

  • nb_max_open_files (int) – The maximum number of files that can be stored in the cache (when the cache is enabled).

File Cache System for Lazy Loading Pattern

Implementation of the caching system for open files in Antares.

The lazy loading feature of many readers works by opening the target file, reading one variable and then closing the file. This is a poor strategy performance-wise since it can potentially mean opening the same file several times (if all the zones and instants are in the same file for example). This is especially true when using the h5py library, since opening the file also means reading the file metadata. Therefore, the solution implemented in this module aims at keeping files open as long as possible for their reuse in the code. This can significantly improve the I/O performance of the code.

The drawbacks of this strategy is that the file descriptors are kept open until the end of the script. This can be potentially dangerous if the user tries to modify an open file externally. For example, the h5py library will not allow to overwrite an already open file, or the OS might create additional hidden files when deleting an open file over an NFS file system. Some of these issues are addressed internally in Antares. Writers using the h5py library will check if the target file is open and they will close the descriptor before writing the new file to the disk. Additionally, the cache keeps track of the modification time to ensure that any open file descriptor has not been modified since the time it was added to the cache. However, not all edge cases can be treated, and the user can close individual files or flush the entire cache if it is necessary.

Main functions

class antares.io.OpenFilesCache.OpenFilesCache(nb_max_open_files=10)

Class to manage cached files.

The OpenFilesCache is a class aiming at keeping open files descriptors for their reuse. This class is especially used in conjunction with the lazy loading feature of many readers. In many readers, the lazy loading is done by opening the file, reading a single variable and closing the file. This is costly if many variables need to be read from a single file (It is especially costly with .h5 files open with h5py, because the file metadata is read every time the file is open). The OpenFilesCache keeps the files descriptor open, avoiding the extra cost of opening the same file many times.

Files can be added or retrieved from this cache via the add_file() and get_file() method. We can also check if a file exists in the cache using the method is_file_open(). Additionally, all the files can be removed from the cache using the method flush().

The cache works by keeping a dictionary whose key is the absolute path of the open files and the values is another dictionary that stores the actual file descriptor and the last time the descriptor was required (via the method get_file()).

This cache limits the number of stored descriptors using the attribute nb_max_open_files (default 10). This is set at the declaration time and it cannot be changed later. When a new file is added, the object checks if adding the new file will not exceed the limit of open files. If it does not, then the file is added. If it does exceed the limit, then the oldest accessed file is removed from the cache and the new file is added. Removing a file from the cache means invoking the close method on the descriptor (WARNING: if the descriptor does not have a close method then an error will be thrown).

add_file(filename, fid)

Add a file descriptor to the list of cached files.

Parameters:

  • filename (str) – path to the file (absolute or relative to the current working directory)

  • fid – Open descriptor of the file

close_file(filename)

Close an specific file in the cache.

Parameters:

filename (str) – path to the file to close (absolute or relative to the current working directory)

enable(nb_max_open_files)

Enable the cache for use.

If this method is called in an already enabled cache, then it will reset the attribute nb_max_open_files. If the new value is greater than the old one, then nothing is done and nb_max_open_files is set to the new value. However, if the new value is lower than the previous value, then the oldest files are closed until the length of the caches is equal to the new nb_max_open_files value.

Parameters:

nb_max_open_files (int) – Number maximum of files that can be stored in the cache

flush()

Close all files in the cache.

get_file(filename)

Get the file descriptor associated to a filename.

An error is thrown if the file is not present in the cache.

Parameters:

filename (str) – path to the file.

Returns:

The file descriptor associated to the filename.

is_file_open(filename)

Check if a file is present in the cache.

Parameters:

filename (str) – path to the file to be checked (absolute or relative to the current working directory)

Returns:

True if the file is present in the cache, False otherwise