.Modelica.Media.UsersGuide.MediumDefinition.BasicStructure

Information

A medium model of Modelica.Media is essentially a package that contains the following definitions:

• Definition of constants, such as the medium name.
• A model in the package that contains the 3 basic thermodynamic equations that relate the 5+nXi primary medium variables.
• Optional functions to compute medium properties that are only needed in certain circumstances, such as dynamic viscosity. These optional functions need not be provided by every medium model.
• Type definitions, which are adapted to the particular medium. For example, a type Temperature is defined where the attributes min and max define the validity region of the medium, and a suitable default start value is given. In a device model, it is advisable to use these type definitions, e.g., for parameters, in order that medium limits are checked as early as possible, and that iteration variables of non-linear systems of equations get reasonable start values.

Note, although we use the term medium model, it is actually a Modelica package that contains all the constants and definitions required for a complete medium model. The basic interface to a medium is defined by Modelica.Media.Interfaces.PartialMedium that has the following structure:

partial package PartialMedium
  import SI = Modelica.SIunits;
  constant String           mediumName = "";
  constant String           substanceNames[:] = {mediumName};
  constant String           extraPropertiesNames[:] = fill("",0);
  constant Boolean          singleState = false;
  constant Boolean          reducedX = true;
  constant Boolean          fixedX = false;
  constant AbsolutePressure reference_p = 101325;
  constant MassFraction     reference_X[nX]=fill(1/nX,nX);
  constant AbsolutePressure p_default = 101325;
  constant Temperature      T_default = Modelica.SIunits.Conversions.from_degC(20);
  constant SpecificEnthalpy h_default =
                            specificEnthalpy_pTX(p_default, T_default, X_default);
  constant MassFraction     X_default[nX]=reference_X;
  final constant Integer    nS  = size(substanceNames,1);
  final constant Integer    nX  = nS;
  final constant Integer    nXi = if fixedX then 0
                                  else if reducedX or nS == 1
                                  then nS-1 else nS;
  final constant Integer    nC  = size(extraPropertiesNames,1);
  constant FluidConstants[nS] fluidConstants;

  replaceable record BasePropertiesRecord
    AbsolutePressure p;
    Density d;
    Temperature T;
    SpecificEnthalpy h;
    SpecificInternalEnergy u;
    MassFraction[nX] X;
    MassFraction[nXi] Xi;
    SpecificHeatCapacity R;
    MolarMass MM;
  end BasePropertiesRecord;

  replaceable partial model BaseProperties
    extends BasePropertiesRecord;
    ThermodynamicState state;
    parameter Boolean preferredMediumStates=false;
    SI.Conversions.NonSIunits.Temperature_degC T_degC =
       Modelica.SIunits.Conversions.to_degC(T)
    SI.Conversions.NonSIunits.Pressure_bar p_bar =
       Modelica.SIunits.Conversions.to_bar(p)
  equation
    Xi = X[1:nXi];
    if nX > 1 then
       if fixedX then
          X = reference_X;
       elseif reducedX then
          X[nX] = 1 - sum(Xi);
       end if;
    end if;
    // equations such as
    //    d = d(p,T);
    //    u = u(p,T);
    //    h = u + p/d;
    //    state.p = p;
    //    state.T = T;
    // will go here in actual media implementations, but are not present
    // in the base class since the ThermodynamicState record is still empty
   end BaseProperties

  replaceable record ThermodynamicState
     // there are no "standard" thermodynamic variables in the base class
     // but they will be defined here in actual media extending PartialMedium
     // Example:
     //    AbsolutePressure p "Absolute pressure of medium";
     //    Temperature      T "Temperature of medium";
  end ThermodynamicState;

  // optional medium properties
  replaceable partial function dynamicViscosity
    input  ThermodynamicState state;
    output DynamicViscosity eta;
  end dynamicViscosity;

  // other optional functions

  // medium specific types
  type AbsolutePressure = SI.AbsolutePressure (
                               min     = 0,
                               max     = 1.e8,
                               nominal = 1.e5,
                               start   = 1.e5);
  type DynamicViscosity = ...;
  // other type definitions
end PartialMedium;

We will discuss all parts of this package in the following paragraphs. An actual medium model should extend from PartialMedium and has to provide implementations of the various parts.

Some of the constants at the beginning of the package do not have a value yet (this is valid in Modelica), but a value has to be provided when extending from package PartialMedium. A given value can be modified until the model is translated or the final prefix is set. The reason to use constants instead of parameters in the model BaseProperties is that some of these constants are used in a context where parameters are not allowed. For example, in connector definitions the number of independent mass fractions nXi is used as dimension of a vector Xi. When defining the connector, only constants in packages can be accessed, but not parameters in a model, because a connector cannot contain an instance of BaseProperties.

The record BasePropertiesRecord contains the variables primarily used in balance equations. Three equations for these variables have to be provided by every medium in model BaseProperties, plus two equations for the gas constant and the molar mass.

Optional medium properties are defined by functions, such as the function dynamicViscosity (see code Section above) to compute the dynamic viscosity. The argument of those functions is the ThermodynamicState record, defined in BaseProperties, which contains the minimum number of thermodynamic variables needed as an input to compute all the optional properties. This construction simplifies the usage considerably as demonstrated in the following code fragment:

  replaceable package Medium = Modelica.Media.Interfaces.PartialMedium;
  Medium.BaseProperties   medium;
  Medium.DynamicViscosity eta;
  ...
  U   = m*medium.u; //Internal energy
  eta = Medium.dynamicViscosity(medium.state);

Medium is the medium package that satisfies the requirements of a PartialMedium (when using the model above, a value for Medium has to be provided by a redeclaration). The medium component is an instance of the model Medium.BaseProperties and contains the core medium equations. Variables in this model can be accessed just by dot-notation, such as medium.u or medium.T. If an optional medium variable has to be computed, the corresponding function from the actual Medium package is called, such as Medium.dynamicViscosity. The medium.state vector can be given as input argument to this function, and its fields are kept consistent to those of BaseProperties by suitable equations, contained in BaseProperties itself (see above).

If a medium model does not provide implementations of all optional functions and one of these functions is called in a model, an error occurs during translation since the optional functions which have not been redeclared have the partial attribute. For example, if function dynamicViscosity is not provided in the medium model when it is used, only simple pressure drop loss models without a reference to the viscosity can be used and not the sophisticated ones.

At the bottom of the PartialMedium package type declarations are present, that are used in all other parts of the PartialMedium package and that should be used in all models and connectors where a medium model is accessed. The reason is that minimum, maximum, nominal, and start values are defined and these values can be adapted to the particular medium at hand. For example, the nominal value of AbsolutePressure is 10⁵ Pa. If a simple model of water steam is used that is only valid above 100 °C, then the minimum value in the Temperature type should be set to this value. The minimum and maximum values are also important for parameters in order to get an early message if data outside of the validity region is given. The nominal attribute is important as a scaling value if the variable is used as a state in a differential equation or as an iteration variable in a non-linear system of equations. The start attribute can be very useful to provide a meaningful default start or guess value if the variable is used, e.g., as iteration variable in a non-linear system of equations. Note, that all these attributes can be set specifically for a medium in the following way:

package MyMedium
  extends Modelica.Media.Interfaces.PartialMedium(
     ...
     Temperature(min=373));
end MyMedium;

The type PartialMedium.MassFlowRate is defined as

type MassFlowRate = Modelica.SIunits.MassFlowRate
     (quantity = "MassFlowRate." + mediumName);

Note that the constant mediumName, that has to be defined in every medium model, is used in the quantity attribute. For example, if mediumName = SimpleLiquidWater, then the quantity attribute has the value MassFlowRate.SimpleLiquidWater. This type should be used in a connector definition of a fluid library:

connector FluidPort
  replaceable package Medium = Modelica.Media.Interfaces.PartialMedium;
  flow Medium.MassFlowRate m_flow;
  ...
end FluidPort;

In the model where this connector is used, the actual Medium has to be defined. Connectors can only be connected together, if the corresponding attributes are either not defined or have identical values. Since mediumName is part of the quantity attribute of MassFlowRate, it is not possible to connect connectors with different media models together.