ship.fmp package

Subpackages

• ship.fmp.datunits package
  • Submodules
  • ship.fmp.datunits.bridgeunit module
  • ship.fmp.datunits.culvertunit module
  • ship.fmp.datunits.gisinfounit module
  • ship.fmp.datunits.htbdyunit module
  • ship.fmp.datunits.initialconditionsunit module
  • ship.fmp.datunits.interpolateunit module
  • ship.fmp.datunits.isisunit module
  • ship.fmp.datunits.junctionunit module
  • ship.fmp.datunits.orificeunit module
  • ship.fmp.datunits.refhunit module
  • ship.fmp.datunits.riverunit module
  • ship.fmp.datunits.spillunit module
  • Module contents

Submodules

ship.fmp.datcollection module

Summary:

Contains the convenience collection pattern UnitCollection. This is used to hold all of the isisunit objects loaded from the dat file. Provides convenience methods for retrieving units and getting key meta-data on the units held in this collection.

Author:

Duncan Runnacles

Created:

01 Apr 2016

Copyright:

Duncan Runnacles 2016

TODO:

Updates:

class DatCollection(path_holder)

Bases: object

Collection of isisunit type classes.

This is a sort of composite/facade for all of the isisunit concrete classes loaded.

Each unit that is loaded is added to this class. They can then be accessed through the convenience methods outlined here.

DIRECTORY = 1

FILENAME = 2

FILENAME_AND_EXTENSION = 3

FULL_PATH = 0

addUnit(unit, index=None, **kwargs)

Adds a new isisunit type to the collection.

If the index value provided is greater than the index of the InitialConditions unit the unit will be added before the IC unit. This is the last slot in the ordering of the units in the dat file.

Accepts **kwargs:

update_node_count(bool): if True will update the node count

value at the top of the .dat file. You probably want to do this. if missing it will default to True

ics(dict): inital conditions to add for the unit being put in the

collection. If missing the default values will be applied. These will only be applied if the unit supports initial conditions.

Parameters:

• unit (AIsisInit) – The instance to add to the collection.
• index=None (int) – Index to insert the unit at.

Raises:

AttributeError – When a non-isisunit type is given.

allUnits()

Get all of the isisunit in the collection

Warning

Don’t use this it is being deprecated and will probably be

removed in a later release.

Returns:list of isisunit objects

Todo

Remove this function it can be accessed through the variables or by setting up a property if needed.

getPrintableContents()

Get the formatted contents of each isisunit in the collection.

Iterates through each of the units in the collection and calls their getData() method.

Returns:

List containing all lines for each unit formatted for printing

out to the dat file.

index(unit, unit_type=None)

Get the index a particular AUnit in the collection.

Either the unit itself or its name can be provided as the argument.

If a name is supplied a unit_type should also be given. This is because some units can have the same name (e.g. river and refh) and it is not possible to know which one to return with the name alone. If no unit_type is given the first unit with the matching name will be returned.

Parameters:

• unit (AUnit or str) – the AUnit or the name of the AUnit to find the index for.
• unit_type=None (str) – the unit_type member of the AUnit (e.g. for a USBPR bridge the unit_category == Bridge and unit_type == ‘Usbpr’).

Returns:

int - the index of the given unit, or -1 if it could not be found.

classmethod initialisedDat(dat_path, units=[], **kwargs)

Create a new ISIS .dat file with basic header info and no units.

Creates the equivelant of generating a new .dat unit in the software. The DatCollection returned can then be manipulated in the same way that any other one loaded from file would be.

A single comment unit will be be added to the file stating that it was created by the SHIP library at timestamp.

Example unit_kwargs. Note that first index is a placholder for no args::

unit_kwargs== [{},

{

‘ics’: {rdt.FLOW: 3.0, rdt.STAGE: 15.0, rdt.ELEVATION: 14.5},

}

]

**kwargs:

unit_kwargs(list): contains a dict with the kwargs for each unit

that is included in units. The list must be the same length as units, or not included. If no kwargs for a particular unit are to be given an empty dict should be used as a placholder in the list.

Parameters:dat_path (str) – the path to set for the newly created .dat file. Returns:DatCollection - setup as an empty ISIS .dat file.

linkedUnits(unit)

numberOfUnits()

The number of units currently held in the collection.

Returns:Int Units in the collection.

removeUnit(unit, unit_type=None, **kwargs)

Remove one of the units previously added to the list.

Accepts **kwargs:

update_node_count(bool): if True will update the node count

value at the top of the .dat file. You probably want to do this. if missing it will default to True

Parameters:

• unit (str | AUnit) – Can either be the AUnit.name or the AUnit.
• unit_type=None (str) – If unit is a name str this must be provided to ensure that the correct unit is removed. E.g. a RiverUnit and an RefhUnit can both have the same AUnit.name value, but different .unit_type’s. If unit is an AUnit this will be ignored.

Raises:

KeyError – if the name doesn’t exist.

setUnit(unit)

Replace the contents of a certain unit with the given one.

Each isisunit have a .name and .unit_type variable. The .nane and .unit_type will be checked against the collection. If the name and matching unit_type is found within thecollection that unit will be replaced with the given one.

Parameters:

unit (AUnit) – the unit to replace.

Raises:

• NameError, AttributeError - if the .name or .unit_type could not
• be found.

unit(key, unit_type=None, unit_category=None)

Fetch a unit from the collection by name.

Each isisunit in the collection is guaranteed to have a unique id. You can access the unit if you know it’s ID. The ID is the AUnit.name variable.

Sometimes different units can have the same name (e.g. RefhUnit and RiverUnit). This function will always return the first unit it finds. To avoid this you can specifiy an AUnit.UNIT_TYPE to retrieve:

>>> getUnit(river.name, river.UNIT_TYPE)

Note that if both unit_type and unit_category are given whichever is found to match against the unit.name first will be returned. This shouldn’t make any difference in practise.

Parameters:

• name_key (str) – name of the unit.
• unit_type=None (str) – the AUnit.TYPE to find.
• unit_category=None (str) – the AUnit.CATEGORY to find.

Returns:

isisunit object corresponding to the given name, or False

if the name doesn’t exist.

unitsByCategory(unit_keys)

Return all the units in the requested unit(s).

Iterate through the collection and get all of the different categories within the model.

Categories are defined by the AUnits. For example: USBPR and Arch bridge units are different, but both will be categorised as ‘bridge’.

Parameters:unit_keys (str | []) – The unit variables defined in the unit. Can be either a string representing a single CATEGORY of AUnit or a list of strings for multiple types. Returns:

List containing all the specified CATEGORY of unit in the model or

False if there are none of the CATEGORY in the collection.

unitsByType(type_keys)

Return all of the units of the requested type.

Iterate through the collection and get all of the different unit types within the model.

Types are set by the isisunit subclasses. They differentiate the from categories by providing further definition. For example: USBPR and ARCH bridges would both be returned in the same UNIT_CATEGORY, but on ARCH bridges would be return using the ArchBridgeUnit.TYPE.

Note

Use the class constants in the isisunit classes as the type key

See also

isisunit.

Parameters:type_keys (str | []) – The unit_type variables defined in the unit. Can be either a string representing a single type of AUnit or a list of strings for multiple types. Returns:List of the specified unit type.

write(filepath=None, overwrite=False)

Write the contents of this file to disk.

Writes out to file in the format required for reading by ISIS/FMP.

Note

If a filepath is not provided and the settings in this objects PathHolder class have not been updated you will write over the file that was loaded.

Parameters:

• filepath=None (str) – if a filename is provided it the file will be written to that location. If not, the current settings in this object path_holder object will be used.
• overwrite=False (bool) – if the file already exists it will raise an IOError.

Raises:

IOError - If unable to write to file.

logger = <logging.Logger object at 0x06A4D710>

logging references with a __name__ set to this module.

ship.fmp.fmpunitfactory module

Summary:

Contains factory classes that are used in the library. At the moment the only factory in here is the IsisFactory. This is used to build the isisunit types.

Author:

Duncan Runnacles

Created:

01 Apr 2016

Copyright:

Duncan Runnacles 2016

TODO:

Updates:

DR - 21/02/16: Major change to the setup of the factory. It no longer scans the .dat file contents to identify the extent of the section and passes only that to the unit. It now identifies the unit type to create and hands the entire contents list to the new unit which extracts the data required.

class FmpUnitFactory

Bases: object

Builds isisunit type objects.

This is a Factory pattern object for the creation of isisunit subclasses.

available_units = (<class 'ship.fmp.datunits.isisunit.HeaderUnit'>, <class 'ship.fmp.datunits.isisunit.CommentUnit'>, <class 'ship.fmp.datunits.riverunit.RiverUnit'>, <class 'ship.fmp.datunits.refhunit.RefhUnit'>, <class 'ship.fmp.datunits.initialconditionsunit.InitialConditionsUnit'>, <class 'ship.fmp.datunits.gisinfounit.GisInfoUnit'>, <class 'ship.fmp.datunits.bridgeunit.BridgeUnitArch'>, <class 'ship.fmp.datunits.bridgeunit.BridgeUnitUsbpr'>, <class 'ship.fmp.datunits.spillunit.SpillUnit'>, <class 'ship.fmp.datunits.htbdyunit.HtbdyUnit'>, <class 'ship.fmp.datunits.junctionunit.JunctionUnit'>, <class 'ship.fmp.datunits.orificeunit.OrificeUnit'>, <class 'ship.fmp.datunits.orificeunit.FloodReliefUnit'>, <class 'ship.fmp.datunits.orificeunit.OutfallUnit'>, <class 'ship.fmp.datunits.culvertunit.CulvertUnitInlet'>, <class 'ship.fmp.datunits.culvertunit.CulvertUnitOutlet'>, <class 'ship.fmp.datunits.interpolateunit.InterpolateUnit'>)

static createUnit(unit_type, **kwargs)

Create a new AUnit.

**kwargs:

‘name’: the name variable to apply to the unit. If not found

‘unknown’ will be set.

‘name_ds’: the name_ds variable to apply to the unit. If not found

‘unknown’ will be set.

head_data: dict of head_data values to set in the AUnit. row_data: dict of row_data keys containing lists of row data to

set in the unit.

no_copy(bool): When adding any row_data given to a new unit the

no_copy flag will be given to the RowDataCollection.addRow() method. When True it stops the call to deepcopy while updating the rows. It’s probably not needed when creating a new unit and it can be time-consuming. The default is True. See RowDataCollection.addRow() for more details.

The row_data kwarg is expected to be set out like the following:

self.brg_rowdata = {
    'main': [
        {rdt.CHAINAGE: 0.0, rdt.ELEVATION: 20.0},
        {rdt.CHAINAGE: 2.0, rdt.ELEVATION: 10.0},
        {rdt.CHAINAGE: 4.0, rdt.ELEVATION: 10.0},
        {rdt.CHAINAGE: 6.0, rdt.ELEVATION: 20.0},
    ],
    'opening': [
        {rdt.OPEN_START: 0.0, rdt.OPEN_END: 2.0},
        {rdt.OPEN_START: 4.0, rdt.OPEN_END: 6.0}
    ]
}

I.e. dict’s of row_data types to update, containing a list of row_vals data to set. These will be used to call the addRow() method in the AUnit. The contents of the list entries will be specific to the unit_type. For more information see the addRow() method and row_data setup of specific AUnit’s.

Parameters:unit_type (str) – the AUnit.UNIT_TYPE to create. Returns:AUnit - the newly created unit.

createUnitFromFile(contents, file_line, file_key, file_order, reach_number=None)

findIcLabels(unit)

getUnitIdentifiers()

Returns all the unit identifiers that the object holds.

Getter for obtaining the identifier strings needed to find the units that have been defined, when loading the dat file.

Parameters:- unit_identifers dictionary. (Dict) –

logger = <logging.Logger object at 0x06A790B0>

logging references with a __name__ set to this module.

ship.fmp.headdata module

Summary:

Contains the HeadDataItem class. Used for storing data types, values, formatting and location of data stored in the head_data dict.

Author:

Duncan Runnacles

Created:

01 Apr 2016

Copyright:

Duncan Runnacles 2016

TODO:

Updates:

class HeadDataItem(initial_value, format_str, line_no, col_no, **kwargs)

Bases: object

Objects stored in the head_data dict in AUnit’s.

Allow for formatting variables and value checks to be encapsulated in one place rather than littered around all subclasses of AUnit.

compare(compare_val)

Check equality of given value against self.value.

Parameters:compare_val – value to compare with self.value. Returns:bool - true if equal, false if not. Raises:ValueError – if value is not the correct type.

format(auto_newline=False)

Return the value converted to unicode str and formatted.

Formatting uses the self.format_str variable.

A newline char ‘

‘ will be appended to the start of the returned

string if it’s col_no == 0 and auto_newline == True.

value

logger = <logging.Logger object at 0x06A79BD0>

logging references with a __name__ set to this module.

ship.fmp.ief module

Summary:

Ief file data holder.

Contains the functionality for loading ISIS .ief files from disk.

Author:

Duncan Runnacles

Created:

01 Apr 2016

Copyright:

Duncan Runnacles 2016

TODO:

Updates:

class Ief(path_holder, header, details, snapshots=None, ied_data=None, description=None)

Bases: object

Contains the details in the in the IEF file.

Class data and a methods for accessing and upating the .ief file.

addIedFile(ied_path, name='')

Add a new ied file.

Parameters:

• ied_path (str) – path to an ied file.
• name='' (str) – name for the ied file.

addSnapshot(snapshot_path, time)

Add a new snapshot.

Parameters:

• snapshot_path (str) – the path for the snapshot.
• time (float) – the time to assign to the snapshot.

getDescription()

Returns the description component of the ief.

getFilePaths()

Returns all the file paths that occur in the ief file.

Most paths are extracted from the head and details data, when they exist, and are added to paths_dict. If any ied data or snapshot data exists it will be added as a list to the dictionary.

If a particular path is not found the value will be set to None, unless, it’s ied or snapshot data in which case it will be an empty list.

Dict keys are: Datafile, Results, InitialConditions, 2DFile, ied, and snapshots.

Returns:dict - containing all of the path data stored by this object.

getIedData()

Get all of the ied data stored in this object.

There can be multiple ied files referenced by an ief. This will return a dictionary containing all of them.

If no ied files are included in the ief file the returned list will be empty.

Returns:ied_path} for all ied files referenced. Return type:dict - containing {ied_name

getPrintableContents()

Return the contents of the file for printing.

Formats the contents of this Ief instance ready to be written back to file.

Returns:List of the formatted lines for printing to file.

Todo

This function is a bit long and messy at the moment. Could do with a good refactoring.

getSnapshots()

Get all of the snapshot data stored in this object.

There can be multiple snapshot files referenced by an ief. This will return a dictionary containing all of them.

If no snapshots are included in the ief file the returned list will be empty.

Returns:

snapshot_path} for all snapshot

files referenced.

Return type:dict - containing {snapshot_time

getValue(key)

Get a value from one of the variables dictionaries.

All single variables (i.e. not lists like ied data) are stored in two main dictionaries. This method will return the value associated with the given key from whichever dictionary it is stored in.

Parameters:key (str) – dict key for value. For a list of available keys use the getAvailableKeys method. Returns:value referenced by the given key, in the ief file. Return type:string Raises:KeyError – if the given key does not exist.

setValue(key, value)

Set the value of one of dictionary entries in the ief.

Parameters:

• key (str) – The key of the value to update.
• value(str( – the value to update.

Raises:

KeyError – if given key is not recongised.

Warning

Currently no checks are made on the validity of the the key given this is because it may be a legal key, but not yet exist in the dictionary. To fix this a list of all valid keys should be created and checked here before setting the value. These are the keys used in the ief file.

write(filepath=None, overwrite=False)

Write the contents of this file to disk.

Writes out to file in the format required for reading by ISIS/FMP.

Note

If a filepath is not provided and the settings in this objects PathHolder class have not been updated you will write over the file that was loaded.

Parameters:

• filepath=None (str) – if a filename is provided it the file will be written to that location. If not, the current settings in this object path_holder object will be used.
• overwrite=False (bool) – if the file already exists it will raise an IOError.

Raises:

IOError - If unable to write to file.

class IefDataTypes

Bases: object

Enum for the different data types within the Ief class.

Use these for easy access of the Ief class.

DESCRIPTION = 4

DETAILS = 1

HEADER = 0

IED_DATA = 2

SNAPSHOTS = 3

logger = <logging.Logger object>

logging references with a __name__ set to this module.

ship.fmp.unitgroups module

Summary:

Contains classes for grouping AUnit types based on certain conditions.

Currently contains:

• LinkedUnits:

  Stores all of the direct associates of a particular unit. See the linkedUnits() method in DatCollection for more information.

Author:

Duncan Runnacles

Created:

02 Dec 2016

Copyright:

Duncan Runnacles 2016

TODO:

Updates:

class LinkedUnits(main_unit)

Bases: object

Stores all units directly associated to a specific unit.

main_unit: the unit to derive associates from. us_unit: the unit immediately above main_unit in the .dat/.ied file. ds_unit: the unit immediately below main_unit in the .dat/.ied file. named_units: all units that are specifically referenced by the main_unit

within it’s head_data (e.g. remote_us and remote_ds in bridge units).

junctions: a list of all of the junctions that refer to the main_unit. Each

list entry contains a tuple where [0] is the JunctionUnit and [1] is a list of units referenced by that junction.

addLinkedUnit(unit, link_type, additionals=None)

Add a unit to this LinkedUnits contents.

Parameters:

• unit – the unit to add.
• link_type (str) – the type of unit being added. Includes: ‘upstream’, ‘downstream’, ‘named’ and ‘junction’.
• additionals=None (list) – used when link_type == ‘junction’ contains a list of all of the units referened by the JunctionUnit.

Module contents