IEF Class#
Summary#
The IEF
class is used to read, write and update Flood Modeller’s ief file format.
The class can be initiated with the full filepath of an ief file to load an existing ief,
or with no path to create a new ief file in memory.
from floodmodeller_api import IEF
ief = IEF('path/to/simulation.ief') # Loads existing IEF into memory
new_ief = IEF() # Used to create new 'blank' IEF
All standard IEF settings can be changed by the user by simply updating the class property with the same name. For example to set the model title, simply type:
ief.title = "My New Title"
Warning
Any changes made to the IEF class object are only made to the object itself and do not change the source IEF file until the
.update()
method is called. Alternatively if the .save()
method is called then the changes are saved to a new file (based on the given
path) and the original source IEF remains unchanged
Class properties can be updated in this fashion for existing IEF settings as well as to add new settings. To remove a particular setting from the IEF simply delete the property object, for example to remove ‘LINKFLOW’ simple type:
del ief.linkflow
Note
IEF properties can be accessed using any casing (e.g. ief.results
is equivalent to
ief.Results
) therefore any scripts using the IEF class can be implemented using
typical python style with lowercase properties, whilst retaining the casing in the original
file.
Class properties can also be managed using python’s built-in getattr()
, setattr()
and delattr()
functions, using these methods is recommended for more
complex updates such as updating settings from a dictionary of values, but is required for certain IEF settings which are prefixed with a number such as ‘2DFLOW’
since these are not valid python variables. An example of updating the ‘2DFLOW’ setting in this way is:
setattr(ief, '2DFLOW', 1) # Sets the IEF's '2DFLOW' setting to 1
IEF files can also be simulated directly by calling the .simulate()
method on an active IEF class object. This method assumes that Flood Modeller is installed
at the default location (‘C:\Program Files\Flood Modeller\bin’). An optional argument 'method'
is used to control whether the python code should pause until the
simulation has completed, or to return the simulation as a subprocess.Popen()
instance and continue code execution. By default, the ‘WAIT’ method is used to provide
a simple way to know when the simulation has completed. Using the option to return the process as an object would mostly be used for more complex scripts where you are
wanting to have more control over checking simulation progress and performing any tasks whilst the simulation is running. Subprocess is a package included in the Python
Standard Library which allows for spawning new processes and handling their input and output pipes. More information on working with subprocess.Popen()
can be found
here.
Working with Event Data attributes#
An IEF file can have any number of ‘EventData’ attributes which point to the location of
IED files. In the IEF class these are all contained within the .eventdata
attribute
as a dictionary. This allows for each event data to have an associated title which is defined in
the IEF file as a comment before the event data attribute. The dictionary keys represent
the titles, and the values represent the event data paths. An example would look like this:
ief = IEF("path/to/file.ief")
ief.eventdata = {
'MainInflow' : 'Q100.IED',
'TribInflow' : 'Q100_trib.IED',
'TidalBoundary' : 'T100_DSBDY.IED'
}
This would then write out the following lines in the IEF file:
;MainInflow
EventData=Q100.IED
;TribInflow
EventData=Q100_trib.IED
;TidalBoundary
EventData=T100_DSBDY.IED
When editing event data attibutes, they can simply be edited in the same way as a dictionary.
For example, deleting keys using del
, adding new keys and editing existing ones.
Warning
The .eventdata
attribute has been changed to use a dictionary as of version 0.4.1 of
the API. Previously in v0.4.0 .eventdata
would return a list instead, without support
for reading/editing the event data titles. This introduces a change which is incompatible
with previous versions of the API in how event data in IEF files is handled. Any existing
code that treats eventdata as a list will need to be updated in order to run this version.
Reference#
- class floodmodeller_api.IEF(ief_filepath: str | Path | None = None, from_json: bool = False)#
Reads and write Flood Modeller event file format ‘.ief’
- Parameters:
ief_filepath (str, optional) – Full filepath to ief file. If not specified, a new IEF class will be created.. Defaults to None.
- Raises:
TypeError – Raised if ief_filepath not pointing to valide IEF file
FileNotFoundError – Raised if ief_filepath points to a non-existent location
Output: Initiates ‘IEF’ class object
- update() None #
Updates the existing IEF based on any altered attributes
- save(filepath: str | Path) None #
Saves the IEF to the given location, if pointing to an existing file it will be overwritten. Once saved, the IEF() class will continue working from the saved location, therefore any further calls to IEF.update() will update in the latest saved location rather than the original source IEF used to construct the class
- Parameters:
filepath (string) – Full filepath to new location for ief file (including ‘.ief’ extension)
- simulate(method: str = 'WAIT', raise_on_failure: bool = True, precision: str = 'DEFAULT', enginespath: str = '', range_function: ~typing.Callable = <function trange>, range_settings: dict | None = None) Popen | None #
Simulate the IEF file directly as a subprocess
- Parameters:
method (str, optional) – {‘WAIT’} | ‘RETURN_PROCESS’ ‘WAIT’ - The function waits for the simulation to complete before continuing (This is default) ‘RETURN_PROCESS’ - The function sets the simulation running in background and immediately continues, whilst returning the process object. Defaults to ‘WAIT’.
raise_on_failure (bool, optional) – If True, an exception will be raised if the simulation fails to complete without errors. If set to False, then the script will continue to run even if the simulation fails. If ‘method’ is set to ‘RETURN_PROCESS’ then this argument is ignored. Defaults to True.
precision (str, optional) – {‘DEFAULT’} | ‘SINGLE’ | ‘DOUBLE’ Define which engine to use for simulation, if set to ‘DEFAULT’ it will use the precision specified in the IEF. Alternatively, this can be overwritten using ‘SINGLE’ or ‘DOUBLE’.
enginespath (str, optional) – {‘’} | ‘/absolute/path/to/engine/executables’ Define where the engine executables are located. This replaces the default location (usual installation folder) if set to anything other than ‘’.
- Raises:
UserWarning – Raised if ief filepath not already specified
- Returns:
If method == ‘RETURN_PROCESS’, the Popen() instance of the process is returned.
- Return type:
subprocess.Popen()
- get_results() ZZN #
If results for the simulation exist, this function returns them as a ZZN class object
- Returns:
floodmodeller_api.ZZN class object
- get_log()#
If log files for the simulation exist, this function returns them as a LF1 class object
- Returns:
floodmodeller_api.LF1 class object
- diff(other: IEF, force_print: bool = False) None #
Compares the IEF class against another IEF class to check whether they are equivalent, or if not, what the differences are. Two instances of an IEF class are deemed equivalent if all of their attributes are equal except for the filepath and raw data.
The result is printed to the console. If you need to access the returned data, use the method
IEF._get_diff()
- Parameters:
other (floodmodeller_api.IEF) – Other instance of an IEF class
force_print (bool) – Forces the API to print every difference found, rather than just the first 25 differences. Defaults to False.
- to_json() str #
Converts the object instance into a JSON string representation.
- Returns:
A JSON string representing the object instance.
- Return type:
str
- classmethod from_json(json_string: str)#
Creates an object instance from a JSON string.
- Parameters:
json_string (str) – A JSON string representation of the object.
- Returns:
An object instance of the class.
Examples#
Example 1 - Update all IEFs in a folder to point to a new DAT file
The following example shows how the IEF class could be used to iteratively update all IEF files in a folder to point to a new DAT file.
# Import modules
from glob import glob
from floodmodeller_api import IEF
# Point to folder of interest
folder = r'C:\FloodModeller_ExampleData\Examples\1D\Flow'
# Get list of IEF files using glob function
ief_files = glob(folder + '\*.ief')
for ief_path in ief_files:
ief = IEF(ief_path) # Initiate IEF Class Object
ief.datafile = r'..\NEW_RIVER_001.DAT' # Set 'Datafile' setting to new DAT file location
ief.update() # Update the IEF file
Example 2 - Create new set of IEFs versions based on previous IEF files
The following example shows how the IEF class could be used to create a new set of IEF files with the title, results and filepath updated to ‘v2’
# Import modules
import od
from glob import glob
from floodmodeller_api import IEF
# Point to folder of interest
folder = r'C:\FloodModeller_ExampleData\Examples\1D\Flow'
# Get list of IEF files using glob function
ief_files = glob(folder + '\*.ief')
for ief_path in ief_files:
ief_name = os.path.basename(ief_path) # get existing filename
new_ief_name = ief_name.replace('.ief', '_v2.ief') # update filename with 'v2' appended
new_ief_path = Path(folder, new_ief_name) # get updated filepath
ief = IEF(ief_path) # Initiate IEF Class Object
ief.title += '_v2' # Update title
try:
ief.results += '_v2' # If Results setting already exists, append v2
except AttributeError:
ief.results = 'v2' # If no results yet specified, set results to v2
ief.save(new_ief_path) # Save updated IEF files to the new filepath
Example 3 - Simulate an IEF and read the results directly
The following example shows how the IEF class could be used to set a simulation going and then access the 1D results directly once it has completed.
# Import modules
from floodmodeller_api import IEF
ief_file = r'path\to\simualtion.ief'
# Instantiate IEF Class object
ief = IEF(ief_file)
# Simulate IEF (the default is for python to wait until simulation is complete)
ief.simulate()
# Access results directly into ZZN class object
zzn = ief.get_results()
# Get dataframe from results
my_results = zzn.to_dataframe()
Example 4 - Simulate an IEF and read the log directly
The following example shows how the IEF class could be used to set a simulation going and then access the log file directly once it has completed.
# Import modules
from floodmodeller_api import IEF
ief_file = r'path\to\simualtion.ief'
# Instantiate IEF Class object
ief = IEF(ief_file)
# Simulate IEF (the default is for python to wait until simulation is complete)
ief.simulate()
# Access results directly into LF1 class object
lf1 = ief.get_log()
# Get dataframe from log file
my_log = lf1.to_dataframe()