Rules v1

A NetCDF-4 file is a said a valid POEM File with version 1 if it complies with the following set of RULES

RULE V1/R0

Freedom to enrich a POEM File with any user data

• Any Attributes for groups or Variables that are not part of the RULES MAY be added for user convenience

• Any Variables that are not part of the RULES MAY be added to groups for user convenience

• Any subgroup MAY be added to groups for user convenience

RULE V1/R1

The special POEM_NODE_TYPE attribute

• Any NetCDF-4 Group, Coordinate Variable or Variable that own a POEM_NODE_TYPE attribute is understood as a POEM object and MUST comply with the associated POEM specification rules when it applies [1]. We call it a POEM group in the following.

• The parent of a POEM group MUST be a POEM group (except for root group)

• The POEM_NODE_TYPE attribute MUST have one of the following values:

Table 2 Valid values for POEM_NODE_TYPE attribute and mapping between NetCDF-4 Data Model et POEM Data Model

POEM_NODE_TYPE	NetCDF-4 object type	POEM object type
POLAR_NODE	group	PolarNode (and not PolarSet or Polar)
POLAR_SET	group	PolarSet
POLAR	group	Polar
POLAR_DIMENSION	Coordinate Variable	Dimension
POLAR_TABLE	Variable	PolarTable

Note

The intent of the POEM_NODE_TYPE is to allow RULE V1/R0 and guarantee the robustness of the mapping between NetCDF-4 Data Model and POEM Data Model (see POEM DATA MODEL).

Note

Although the rules of the specification are about NetCDF-4 objects (groups, Coordinate Variables or Variables), in the following we will talk about POEM objects instead of the NetCDF-4 counterpart, to avoid overloading the text.

So for example, if we talk about a PolarSet, we are talking about a NetCDF-4 group with an attribute POEM_NODE_TYPE with the value POLAR_SET

[1]

Conversely, any NetCDF-4 group, Coordinate Variable or Variable that DO NOT own the POEM_NODE_TYPE attribute is not read by the POEM Library

RULE V1/R2

Root Group mandatory global attributes

• Root group MUST have the global attribute POEM_SPECIFICATION_VERSION with POEM File Format Specification set to 1

• Root group MUST have the global attribute VESSEL_NAME filled with the vessel name

• Root group MUST have the global attribute POEM_NODE_TYPE. Value of this attribute depends on the context

RULE V1/R3

Required hierarchy elements

• A PolarSet ALWAYS owns at least a Polar

• A Polar ALWAYS owns at least a PolarTable with associated Dimensions (see also RULE V1/R7)

• Every of the PolarTables owned by a same Polar MUST have the same Dimension dependency (i.e. same DimensionSet in POEM Data Model), with the exact same order

• A POEM File ALWAYS owns at least one Polar

RULE V1/R4

Polar group names and POEM_MODE attribute

• A Polar group MUST own a POEM_MODE attribute with value corresponding to the POLAR MODE it represents

• If a Polar group is not the root group, its name MUST be the same as the attribute POEM_MODE

• The case for POEM_MODE MUST be respected

RULE V1/R5

Mandatory attributes

• Any POEM object (RULE V1/R1) MUST have the following attribute

  • description: a one small sentence description of the variable

• Any Dimension and PolarTable MUST also have the following attribute

  • unit: specifies the unit of the Variable

• The unit attribute MUST comply with d-units library recognized units (TODO: TO BE DOCUMENTED…)

RULE V1/R6

Dimensions values

• Dimensions values vectors MUST be list of positive, strictly increasing numbers

• Angular Dimension values MUST be between 0 and 180 degrees

• Dimensions values MAY have non-uniform value vectors

Note

Currently, the only accepted Angular Dimension unit accepted is deg. This limitation could be removed in the future if needed

RULE V1/R7

Minimal mandatory Dimensions and PolarTables in Polar

• The following Dimensions and PolarTables MUST be present in Polar, with list depending on the POLAR mode that is encoded in the Polar name

	MPPP	HPPP	MVPP	HVPP	VPP	Unit	Description
Mandatory Dimensions
STW_dim	X	X				kt	Speed Through Water dimension
Power_dim [2]			X	X		kW	Power dimension
TWS_dim	X	X	X	X	X	kt	True Wind Speed dimension
TWA_dim	X	X	X	X	X	deg	True Wind Angle dimension
WA_dim	X	X	X	X	X	deg	Mean Waves Angle dimension
Hs_dim	X	X	X	X	X	m	Wave Significant Height
Minimal Mandatory PolarTables
STW			X	X	X	kt	Speed Through Water
TOTAL_POWER [3]	X	X				kW	Total Power Consumption
LEEWAY	X	X	X	X	X	deg	Leeway Angle
SOLVER_STATUS [4]	X	X	X	X	X	–	Solver Status

• Case for the Dimension and PolarTables MUST be respected

[2]

Power_dim dimension is most of the time the Power associated to propulsion, i.e. BrakePower. But other convention can be used but it must documented.

[3]

TOTAL_POWER PolarTable is the total consummed power onboard (propulsion power, power consummed by sails, hotel load etc…). What is accounted for must be documented

[4]

SOLVER_STATUS is a special PolarTable whose data are integers. It is used to specify if a polar point comes from a successful computation (e.g. convergence of solver, constraints satisfied) or not. 0 means success, i.e. it can be used. Any other value means not successful. Other PolarTable values corresponding to a PolarPoint for which the SOLVER_STATUS is non zero can have any value such as 0 or NaN. SOLVER_STATUS value should be used as the main source of information about quality of data. User can use its own non zero values to specify special cases of non-convergence of the solvers.