Available models

This page gives an overview about all available models in PowerSystemDataModel. They are basically grouped into three groups:

  1. Input models may be used to describe input data for a power system simulation

  2. Result models denote results of such a simulation

  3. Time Series may serve both as input or output

All those models are designed with some assumptions and goals in mind. To assist you in applying them as intended, we will give you some general remarks:

Uniqueness

All models have a uuid field as universal unique identifier. There shouldn’t be any two elements with the same uuid in your grid data set, better in your whole collection of data sets.

Immutability

We designed the models in a way, that does not allow for adaptions of the represented data after instantiation of the objects. Thereby you can be sure, that your models are thread-safe and no unwanted or unobserved changes are made.

Copyable

With the general design principle of immutability, entity modifications (e.g. updates of field values) can become hard and annoying. To avoid generating methods to update each field value, we provide an adapted version of the builder pattern to make entity modifications as easy as possible. Each entity holds it’s own copy builder class, which follows the same inheritance as the entity class itself. With a call of .copy() on an entity instance a builder instance is returned, that allows for modification of fields and can be terminated with .build() which will return an instance of the entity with modified field values as required. For the moment, this pattern is only implemented for a small amount of AssetInput entities (all entities held by a GridContainer except thermal units to be precise), but we plan to extend this capability to all input entities in the future.

Single Point of Truth

Throughout all models you can be sure, that no information is given twice, reducing the possibility to have ambiguous information in your simulation set up. “Missing” information can be received through the grids relational information - e.g. if you intend to model a wind energy converter in detail, you may find information of it’s geographical location in the model of it’s common coupling point (node).

Harmonized Units System

As our models are representations of physical elements, we introduced a harmonized system of units. The standard units, the models are served with, is given on each element’s page. Thereby you can be sure, that all information are treated the same. As most (database) sources do not support physical units, make sure, you have your input data transferred to correct units before. Same applies for interpreting the obtained results. In all models physical values are transferred to standard units on instantiation.

Equality Checks

To represent quantities in the models within an acceptable accuracy, the JSR 385 reference implementation Indriya is used. Comparing quantity objects or objects holding quantity instances is not as trivial as it might seem, because there might be different understandings about the equality of quantities (e.g. there is a big difference between two instances being equal or equivalent). After long discussions how to treat quantities in the entity equals() method, we agreed on the following rules to be applied:

  • equality check is done by calling Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>) or <QuantityInstanceA>.equals(<QuantityInstanceB>). Using Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>) is necessary especially for time series data. As in contrast to all other places, quantity time series from real world data sometimes are not complete and hence contain missing values. To represent missing values this is the only place where the usage of null is a valid choice and hence needs to be treated accordingly. Please remember that this is only allowed in very few places and you should try to avoid using null for quantities or any other constructor parameter whenever possible!

  • equality is given if, and only if, the quantities value object and unit are exactly equal. Value objects can become e.g. BigDecimal or Double instances. It is important, that the object type is also the same, otherwise the entities equals() method returns false. This behavior is in sync with the equals implementation of the indriya library. Hence, you should ensure that your code always pass in the same kind of a quantity instance with the same underlying number format and type. For this purpose you should especially be aware of the unit conversion method AbstractQuantity.to(Quantity) which may return seemingly unexpected types, e.g. if called on a quantity with a double typed value, it may return a quantity with a value of either Double type or BigDecimal type.

  • for now, there is no default way to compare entities in a ‘number equality’ way provided. E.g. a line with a length of 1km compared to a line with a length of 1000m is actually of the same length, but calling LineA.equals(LineB) would return false as the equality check does NOT convert units. If you want to compare two entity instances based on their equivalence you have (for now) check for each quantity manually using their isEquivalentTo() method. If you think you would benefit from a standard method that allows entity equivalence check, please consider handing in an issue here. Furthermore, the current existing implementation of isEquivalentTo() in indriya does not allow the provision of a tolerance threshold that might be necessary when comparing values from floating point operations. We consider providing such a method in our PowerSystemUtils library. If you think you would benefit from such a method, please consider handing in an issue here.

Conditional Parameters

Some of the models have conditional parameters. When reading model data from a data source, their respective factories for building these models can handle nulls and empty Strings (as well as any combination of those) safely. E.g.: When given parameters for a line’s operationTime where operationStartTime and operationEndTime are both null or "", the factory will build an always-on line model.

Input

Model classes you can use to describe a data set as input to power system simulations.

Result

Model classes you can use to describe the outcome of a power system simulation.

Grid Related Models

Participant Related Models

Time Series

Time series are meant to represent a timely ordered series of values. Those can either be electrical or non-electrical depending on what one may need for power system simulations. Our time series models are divided into two subtypes:

Individual Time Series

Each time instance in this time series has its own value (random duplicates may occur obviously). They are only applicable for the time frame that is defined by the content of the time series.

Repetitive Time Series

Those time series do have repetitive values, e.g. each day or at any other period. Therefore, they can be applied to any time frame, as the mapping from time instant to value is made by information reduction. In addition to actual data, a mapping function has to be known.

To be as flexible, as possible, the actual content of the time series is given as children of the Value class. The following different values are available:

Value Class

Purpose

PValue

Electrical active power

SValue

Electrical active and reactive power

HeatAndPValue

Combination of thermal power (e.g. in kW)
and electrical active power (e.g. in kW)

HeatAndSValue

Combination of thermal power (e.g. in kW)
and electrical active and reactive power (e.g. in kW and kVAr)

EnergyPriceValue

Wholesale market price (e.g. in € / MWh)

SolarIrradianceValue

Combination of diffuse and direct solar irradiance

TemperatureValue

Temperature information

WindValue

Combination of wind direction and wind velocity

WeatherValue

Combination of irradiance, temperature and wind information

Validation Utils

This page gives an overview about the ValidationUtils in the PowerSystemDataModel.

What are the ValidationUtils?

The methods in ValidationUtils and subclasses can be used to check that objects are valid, meaning their parameters have valid values and they are correctly connected.

What is checked?

  • The check methods include checks that assigned values are valid, e.g. lines are not allowed to have negative lengths or the rated power factor of any unit must be between 0 and 1.

  • Furthermore, several connections are checked, e.g. that lines only connect nodes of the same voltage level or that the voltage levels indicated for the transformer sides match the voltage levels of the nodes they are connected to.

How does it work?

  • The method ValidationUtils.check(Object) is the only method that should be called by the user.

  • This check method identifies the object class and forwards it to a specific check method for the given object

  • The overall structure of the ValidationUtils methods follows a cascading scheme, orientated along the class tree

  • Example: A LineInput lineInput should be checked
    1. ValidationUtils.check(lineInput) is called

    2. ValidationUtils.check(lineInput) identifies the class of the object as AssetInput and calls ValidationUtils.checkAsset(lineInput)

    3. ValidationUtils.checkAsset(lineInput), if applicable, checks those parameters that all AssetInput have in common (e.g. operation time) and further identifies the object, more specifically, as a ConnectorInput and calls ConnectorValidationUtils.check(lineInput)

    4. ConnectorValidationUtils.check(lineInput), if applicable, checks those parameters that all ConnectorInput have in common and further identifies the object, more specifically, as a LineInput and calls ConnectorValidationUtils.checkLine(lineInput)

    5. ConnectorValidationUtils.checkLine(lineInput) checks all specific parameters of a LineInput

  • ValidationUtils furthermore contains several utils methods used in the subclasses

Which objects are checked?

The ValidationUtils include validation checks for…

  • NodeValidationUtils
    • NodeInput

    • VoltageLevel

  • ConnectorValidationUtils:
    • ConnectorInput
      • LineInput

      • Transformer2WInput

      • Transformer3WInput

      • SwitchInput

    • ConnectorTypeInput
      • LineTypeInput

      • Transformer2WTypeInput

      • Transformer3WTypeInput

  • MeasurementUnitValidationUtils
    • MeasurementUnitInput

  • SystemParticipantValidationUtils
    • SystemParticipantInput
      • BmInput

      • ChpInput

      • EvInput

      • FixedFeedInInput

      • HpInput

      • LoadInput

      • PvInput

      • StorageInput

      • WecInput

      • (missing: EvcsInput)

    • SystemParticipantTypeInput
      • BmTypeInput

      • ChpTypeInput

      • EvTypeInput

      • HpTypeInput

      • StorageTypeInput

      • WecTypeInput

      • (missing: EvcsTypeInput/ChargingPointType)

  • ThermalUnitValidationUtils
    • ThermalUnitInput
      • ThermalSinkInput
        • ThermalHouseInput

      • ThermalStorageInput
        • CylindricalStorageInput

  • GraphicValidationUtils
    • GraphicInput
      • LineGraphicInput

      • NodeGraphicInput

  • GridContainerValidationUtils
    • GraphicElements

    • GridContainer

    • RawGridElements

    • SystemParticipants

What should be considered?

  • Due to many checks with if-conditions, the usage of the ValidationUtils for many objects might be runtime relevant.

  • The check for a GridContainer includes the interplay of the contained entities as well as the checks of all contained entities.

  • If new classes are introduced to the PowerSystemDataModel, make sure to follow the forwarding structure of the ValidationUtils methods when writing the check methods!