Version_3_0

Version 3.0 (March 1, 2008)

    Version_3_0

Library

Modelica/UsersGuide/ReleaseNotes

Description

Version 3.0 is not backward compatible to previous versions. A conversion script is provided to transform models and libraries of previous versions to the new version. Therefore, conversion should be automatic.

The following changes are present for the whole library:

  • In the Modelica language version 3.0, several restrictions have been introduced to allow better checking, e.g., models on all levels must be balanced (number of equations = number of unknown variables - unknown variables that have to be defined when using the component). A few models of the Modelica Standard Library did not fulfill these new restrictions and had either to be moved to library ObsoleteModelica3 (e.g., Blocks.Math.TwoInputs) or had to be differently implemented (e.g., Media.Interfaces.PartialMedium.BaseProperties). The Modelica Standard Library version 3.0 fulfills all the restrictions of the Modelica Language version 3.0.
     
  • The graphical annotations describing the layout of icon and diagram layer are changed from Modelica language version 1 to Modelica language version 3. This gives several significant improvements:
    Especially, the coordinate systems of icon and diagram layers are no longer coupled and therefore the size of the icon layer can be changed independently of the size of the diagram layer. Also it can be defined that the aspect ratio of a component icon is kept when changing its size in a model. This flag is set so that all icons of the Modelica Standard Library keep its aspect ratios. This is slightly non-backward compatible: If the aspect ratio was not kept when using a component from the Modelica Standard Library, it is now resized so that the aspect ratio is maintained.
     
  • All non-standard annotations removed by:
    (1) Removing the annotation since without effect (e.g., "__Dymola_experimentSetupOutput", "Window", "Terminal" removed).
    (2) Renaming the annotation to a standard name (e.g., "Hide" renamed to "HideResult").
    (3) Renaming the annotation to a vendor specific name (e.g., "checkBox" renamed to "__Dymola_checkBox").
     
  • All emulated enumerations (defined via packages and constants) have been replaced by "real" enumerations. User models are automatically correctly converted, provided the user models used the package constants previously. Existing models that use directly literal values for enumerations, might give in some cases wrong results (if the first constant of the emulated enumeration had value zero, whereas the first value of an enumeration is one).
     
  • The operator "cardinality" will be removed in one of the next versions of the Modelica language, since it is a reflective operator and its usage significantly reduces the possibilities of advanced model checks (e.g., to guarantee that a model is "balanced", i.e., the number of equations and unknowns is identical, for all valid usages of the component). As a preparation for this change, all models that contain the "cardinality(..)" operator are rewritten: If possible the operator is removed. If this is not possible, it is only used in asserts to check that, e.g., a connector is connected at least once or is connected exactly once. In the next Modelica language version new language elements will be introduced to specify such a property check without the cardinality operator. Once these language elements are available, the cardinality operator will be removed completely from the Modelica Standard Library.
    The changes with respect to the cardinality(..) operator are usually not backward compatible. This is the reason for the changes of the Rotational and Translational library (see below).
     
  • The design of the Rotational and Translational libraries have been changed (especially to remove the cardinality(..) operator, see above):
    • Components have a useSupport flag to enable or disable a support flange. If the support flange is enabled, it must be connected. If it is disabled, it must not be connected and the component is then internally grounded. The grounding is visualized in the icon.
    • The relative angle/distance and the relative speed of all force/torque elements (that need the relative speed) are by default defined with "StateSelect.prefer", i.e., to use these variables as preferred states. This improves the numerics if the absolute angle or the absolute distance are continuously increasing during operation (e.g., driving shaft of the wheels of a car). The effect is that relative angles/distances and speeds are used as states and the size of these variables is limited. Previously, the default was to use the absolute angle/distance and absolute speed of every inertia/mass which has the disadvantage that the absolute angle and or distance are state variables that grow in size continuously.
      A significant advantage is also, that default initialization is usually better, because a default value of zero for a relative angle/distance is usually what the user would like to have. Previously, say, the load was initialized to a non-zero angle and then the elastically coupled motor inertia had to be explicitly also initialized with this value. This is now, no longer needed. Since the default nominal value of 1 is usually too large for a relative quantity, the nominal values of the relative angle/distance was changed to 1e-4.
    • The two libraries have been restructured in sublibraries to cope with the growing number of components.
    • Finally, the Translational library has been made as similar as possible to the Rotational library by, e.g., adding missing components.
       
  • The initialization of the MultiBody, Rotational and Translational libraries have been significantly simplified by removing the "initType" parameters and only using start/fixed values. This design assumes that a tool has special support for start/fixed values in the parameter menu.
     
  • Nearly all parameters defined in the Modelica Standard Library had been defined with a default equation, e.g.,
       parameter Modelica.SIunits.Resistance R=1; 
    Physical parameters, such as a resistance, mass, gear ratio, do not have a meaningful default and in nearly all cases, the user of the corresponding component has to provide values for such parameters. If the user forgets this, a tool cannot provide diagnostics, since a default value is present in the library (such as 1 Ohm for the resistance). In most cases the model will simulate but will give wrong results due to wrong parameter values. To improve this situation, all physical parameter declarations in the Modelica Standard Library have been changed, so that the previous default becomes a start value. For example, the above declaration is changed to:
       parameter Modelica.SIunits.Resistance R(start=1);  
    This is a backward compatible change and completely equivalent from the perspective of the Modelica language. It is, however, advised that tools will print a warning or optionally an error message, if the start value of a parameter is defined, but no value for the parameter is given via a modification. Furthermore, it is expected, that the input field of a parameter menu is empty, if no default equation is defined, but only a start value. This shows clearly to the modeler that a value has to be provided.


The following new components have been added to existing libraries (note, the names in parentheses are the new sublibrary names that are introduced in version 3.0):

Blocks.Examples.
InverseModel Demonstrates the construction of an inverse model.
Blocks.Math.
InverseBlockConstraints Construct inverse model by requiring that two inputs and two outputs are identical (replaces the previously, unbalanced, TwoInputs and TwoOutputs blocks).
Electrical.Machines.Utilities
TransformerData A record that calculates required impedances (parameters) from nominal data of transformers.
Mechanics.MultiBody.Examples.Rotational3DEffects
GyroscopicEffects
ActuatedDrive
MovingActuatedDrive
GearConstraint
New examples to demonstrate the usage of the Rotational library in combination with multi-body components.
Mechanics.MultiBody.Sensors
AbsolutePosition
AbsoluteVelocity
AbsoluteAngles
AbsoluteAngularVelocity
RelativePosition
RelativeVelocity
RelativeAngles
RelativeAngularVelocity
New sensors to measure one vector.
TransformAbsoluteVector
TransformRelativeVector
Transform absolute and/or relative vector into another frame.
Mechanics.Rotational.(Components)
Disc Right flange is rotated by a fixed angle with respect to left flange
IdealRollingWheel Simple 1-dim. model of an ideal rolling wheel without inertia
Mechanics.Translational.Sensors
RelPositionSensor
RelSpeedSensor
RelAccSensor
PowerSensor
Relative position sensor, i.e., distance between two flanges
Relative speed sensor
Relative acceleration sensor
Ideal power sensor
Mechanics.Translational(.Components)
SupportFriction
Brake
InitializeFlange
Model of friction due to support
Model of a brake, base on Coulomb friction
Initializes a flange with pre-defined position, speed and acceleration .
Mechanics.Translational(.Sources)
Force2
LinearSpeedDependentForce
QuadraticSpeedDependentForce
ConstantForce
ConstantSpeed
ForceStep
Force acting on 2 flanges
Force linearly dependent on flange speed
Force quadratic dependent on flange speed
Constant force source
Constant speed source
Force step


The following existing components have been changed in a non-backward compatible way (the conversion script transforms models and libraries of previous versions to the new version. Therefore, conversion should be automatic):

Blocks.Continuous.
CriticalDamping New parameter "normalized" to define whether filter is provided in normalized or non-normalized form. Default is "normalized = true". The previous implementation was a non-normalized filter. The conversion script automatically introduces the modifier "normalized=false" for existing models.
Blocks.Interfaces.
RealInput
RealOutput
Removed "SignalType", since extending from a replaceable class and this is not allowed in Modelica 3.
The conversion script removes modifiers to SignalType.
RealSignal
IntegerSignal
BooleanSignal
Moved to library ObsoleteModelica3, since these connectors are no longer allowed in Modelica 3
(prefixes input and/or output are required).
Blocks.Interfaces.Adaptors.
AdaptorReal
AdaptorBoolean
AdaptorInteger
Moved to library ObsoleteModelica3, since the models are not "balanced". These are completely obsolete adaptors
between the Real, Boolean, Integer signal connectors of version 1.6 and version ≥ 2.1 of the Modelica Standard Library.
Blocks.Math.
ConvertAllUnits Moved to library ObsoleteModelica3, since extending from a replaceable class and this is not allowed in Modelica 3.
It would be possible to rewrite this model to use a replaceable component. However, the information about the conversion
cannot be visualized in the icon in this case.
Blocks.Math.UnitConversions.
TwoInputs
TwoOutputs
Moved to library ObsoleteModelica3, since the models are not "balanced". A new component
"InverseBlockConstraints" is provided instead that has the same feature, but is "balanced".
Electrical.Analog.Baisc.
HeatingResistor The heatPort has to be connected; otherwise the component Resistor (without heatPort) has to be used.
cardinality() is only used to check whether the heatPort is connected.
Electrical.MultiPhase.Examples.
Changed the instance names of components used in the examples to more up-to-date style.
Electrical.Machines.
Moved package Machines.Examples.Utilities to Machines.Utilities
Removed all nonSIunits; especially in DCMachines
parameter NonSIunits.AngularVelocity_rpm rpmNominal was replaced by
parameter SIunits.AngularVelocity wNominal
Changed the following component variable and parameter names to be more concise:
Removed suffix "DamperCage" from all synchronous induction machines since the user can choose whether the damper cage is present or not.
RotorAngle ... RotorDisplacementAngle
J_Rotor ... Jr
Rr ........ Rrd (damper of synchronous induction machines)
Lrsigma ... Lrsigmad (damper of synchronous induction machines)
phi_mechanical ... phiMechanical
w_mechanical ..... wMechanical
rpm_mechanical ... rpmMechanical
tau_electrical ... tauElectrical
tau_shaft ........ tauShaft
TurnsRatio ....... turnsRatio (AIMS)
VsNom ............ VsNominal (AIMS)
Vr_Lr ............ VrLockedRotor (AIMS)
DamperCage ....... useDamperCage (synchronous induction machines)
V0 ............... VsOpenCicuit (SMPM)
Ie0 .............. IeOpenCicuit (SMEE)
Interfaces. Moved as much code as possible from specific machine models to partials to reduce redundant code.
Interfaces.Adapter Removed to avoid cardinality; instead, the following solution has been implemented:
Sensors.RotorDisplacementAngle
Interfaces.PartialBasicMachine
Introduced parameter Boolean useSupport=false "enable / disable (=fixed stator) support"
The rotational support connector is only present with useSupport = true;
otherwise the stator is fixed internally.
Electrical.Machines.Examples.
Changed the names of the examples to more meaningful names.
Changed the instance names of components used in the examples to more up-to-date style.
SMEE_Generator Initialization of smee.phiMechanical with fixed=true
Mechanics.MultiBody.
World Changed default value of parameter driveTrainMechanics3D from false to true.
3-dim. effects in Rotor1D, Mounting1D and BevelGear1D are therefore taken
into account by default (previously this was only the case, if world.driveTrainMechanics3D was explicitly set).
Mechanics.MultiBody.Forces.
FrameForce
FrameTorque
FrameForceAndTorque
Models removed, since functionality now available via Force, Torque, ForceAndTorque
WorldForce
WorldTorque
WorldForceAndTorque
Force
Torque
ForceAndTorque
Connector frame_resolve is optionally enabled via parameter resolveInFrame
. Forces and torques and be resolved in all meaningful frames defined by enumeration resolveInFrame.
Mechanics.MultiBody.Frames.
length
normalize
Removed functions, since available also in Modelica.Math.Vectors
The conversion script changes the references correspondingly.
Mechanics.MultiBody.Joints.
Prismatic
ActuatedPrismatic
Revolute
ActuatedRevolute
Cylindrical
Universal
Planar
Spherical
FreeMotion
Changed initialization, by replacing initial value parameters with start/fixed attributes.
When start/fixed attributes are properly supported in the parameter menu by a Modelica tool,
the initialization is considerably simplified for the user and the implementation is much simpler.
Replaced parameter "enforceStates" by the more general built-in enumeration stateSelect=StateSelection.xxx.
The conversion script automatically transforms from the "old" to the "new" forms.
Revolute
ActuatedRevolute
Parameter "planarCutJoint" in the "Advanced" menu of "Revolute" and of "ActuatedRevolute" removed.
A new joint "RevolutePlanarLoopConstraint" introduced that defines the constraints of a revolute joint
as cut-joint in a planar loop. This change was needed in order that the revolute joint can be properly used
in advanced model checking.
ActuatedRevolute joint removed. Flange connectors of Revolute joint
can be enabled with parameter useAxisFlange.
Prismatic
ActuatedPrismatic
ActuatedPrismatic joint removed. Flange connectors of Prismatic joint
can be enabled with parameter useAxisFlange.
Assemblies Assembly joint implementation slightly changed, so that annotation "structurallyIncomplete"
could be removed (all Assembly joint models are now "balanced").
Mechanics.MultiBody.Joints.Internal
RevoluteWithLengthConstraint
PrismaticWithLengthConstraint
These joints should not be used by a user of the MultiBody library. They are only provided to built-up the MultiBody.Joints.Assemblies.JointXYZ joints. These two joints have been changed in a slightly not backward compatible way, in order that the usage in the Assemblies.JointXYZ joints results in balanced models (no conversion is provided for this change since the user should not have used these joints and the conversion would be too complicated): In releases before version 3.0 of the Modelica Standard Library, it was possible to activate the torque/force projection equation (= cut-torque/-force projected to the rotation/translation axis must be identical to the drive torque/force of flange axis) via parameter axisTorqueBalance. This is no longer possible, since otherwise this model would not be "balanced" (= same number of unknowns as equations). Instead, when using this model in version 3.0 and later versions, the torque/force projection equation must be provided in the Advanced menu of joints Joints.SphericalSpherical and Joints.UniversalSpherical via the new parameter "constraintResidue".
Mechanics.MultiBody.Parts.
BodyBox
BodyCylinder
Changed unit of parameter density from g/cm3 to the SI unit kg/m3 in order to allow stricter unit checking.
The conversion script multiplies previous density values with 1000.
Body
BodyShape
BodyBox
BodyCylinder
PointMass Rotor1D
Changed initialization, by replacing initial value parameters with start/fixed attributes.
When start/fixed attributes are properly supported in the parameter menu by a Modelica tool,
the initialization is considerably simplified for the user and the implementation is much simpler.
The conversion script automatically transforms from the "old" to the "new" form of initialization.
Mechanics.MultiBody.Sensors.
AbsoluteSensor
RelativeSensor
CutForceAndTorque
New design of sensor components: Via Boolean parameters
signal connectors for the respective vectors are enabled/disabled.
It is not possible to automatically convert models to this new design.
Instead, references in existing models are changed to ObsoleteModelice3.
This means that these models must be manually adapted.
CutForce
CutTorque
Slightly new design. The force and/or torque component can be resolved in world, frame_a, or frame_resolved.
Existing models are automatically converted.
Mechanics.Rotational.
Moved components to structured sub-packages (Sources, Components)
Inertia
SpringDamper
RelativeStates
Changed initialization, by replacing initial value parameters with start/fixed attributes.
When start/fixed attributes are properly supported in the parameter menu by a Modelica tool,
the initialization is considerably simplified for the user and the implementation is much simpler.
Parameter "stateSelection" in "Inertia" and "SpringDamper" replaced by the built-in enumeration
stateSelect=StateSelection.xxx. Introduced the "stateSelect" enumeration in "RelativeStates".
The conversion script automatically transforms from the "old" to the "new" forms.
LossyGear
GearBox
Renamed gear ratio parameter "i" to "ratio", in order to have a consistent naming convention.
Existing models are automatically converted.
SpringDamper
ElastoBacklash
Clutch
OneWayClutch
Relative quantities (phi_rel, w_rel) are used as states, if possible (due to StateSelect.prefer).
In most cases, relative states in drive trains are better suited as absolute states.
This change might give changes in the selected states of existing models.
This might give rise to problems if, e.g., the initialization was not completely defined in a user model,
since the default initialization heuristic may give different initial values.
Mechanics.Translational.
Moved components to structured sub-packages (Sources, Components)
Adaptions corresponding to Rotational
Stop Renamed to Components.MassWithStopAndFriction to be more concise.
MassWithStopAndFriction is not available with a support connector,
since the reaction force can't be modeled in a meaningful way due to reinit of velocity v.
Until a sound implementation of a hard stop is available, the old model may be used.
Media.
constant nX
constant nXi
constant reference_X
BaseProperties
The package constant nX = nS, now always, even for single species media. This also allows to define mixtures with only 1 element. The package constant nXi=if fixedX then 0 else if reducedX or nS==1 then nS - 1 else nS. This required that all BaseProperties for single species media get an additional equation to define the composition X as {1.0} (or reference_X, which is {1.0} for single species). This will also mean that all user defined single species media need to be updated by that equation.
SIunits.
CelsiusTemperature Removed, since no SI unit. The conversion script changes references to SIunits.Conversions.NonSIunits.Temperature_degC
ThermodynamicTemperature
TemperatureDifference
Added annotation "absoluteValue=true/false" in order that unit checking is possible
(the unit checker needs to know for a unit that has an offset, whether it is used as absolute or as a relative number)
SIunits.Conversions.NonSIunits.
Temperature_degC
Temperature_degF
Temperature_degRk
Added annotation "absoluteValue=true" in order that unit checking is possible
(the unit checker needs to know for a unit that has an offset, whether it is used as absolute or as a relative number)
StateGraph.Examples.
ControlledTanks The connectors of the ControlledTanks did not fulfill the new restrictions of Modelica 3. This has been fixed.
Utilities Replacing inflow, outflow by connectors inflow1, inflow2, outflow1, outflow2 with appropriate input/output prefixes in order to fulfill the restrictions of Modelica 3 to arrive at balanced models. No conversion is provided, since too difficult and since the non-backward compatible change is in an example.
Thermal.FluidHeatFlow.Sensors.

pSensor
TSensor
dpSensor
dTSensor
m_flowSensor
V_flowSensor
H_flowSensor
renamed to:
PressureSensor
TemperatureSensor
RelPressureSensor
RelTemperatureSensor
MassFlowSensor
VolumeFlowSensor
EnthalpyFlowSensor
Thermal.FluidHeatFlow.Sources.
Ambient
PrescribedAmbient
available as one combined component Ambient
Boolean parameters usePressureInput and useTemperatureInput decide whether pressure and/or temperature are constant or prescribed
ConstantVolumeFlow
PrescribedVolumeFlow
available as one combined component VolumeFlow
Boolean parameter useVolumeFlowInput decides whether volume flow is constant or prescribed
ConstantPressureIncrease
PrescribedPressureIncrease
available as one combined component PressureIncrease
Boolean parameter usePressureIncreaseInput decides whether pressure increase is constant or prescribed
Thermal.FluidHeatFlow.Examples.
Changed the instance names of components used in the examples to more up-to-date style.
Thermal.HeatTransfer.(Components)
HeatCapacitor Initialization changed: SteadyStateStart removed. Instead start/fixed values for T and der_T
(initial temperature and its derivative).


HeatCapacitor
ThermalConductor
ThermalConvection
BodyRadiation

TemperatureSensor
RelTemperatureSensor
HeatFlowSensor

FixedTemperature
PrescribedTemperature
FixedHeatFlow
PrescribedHeatFlow
Moved components to sub-packages:

Components.HeatCapacitor
Components.ThermalConductor
Components.ThermalConvection
Components.BodyRadiation

Sensors.TemperatureSensor
Sensors.RelTemperatureSensor
Sensors.HeatFlowSensor

Sources.FixedTemperature
Sources.PrescribedTemperature
Sources.FixedHeatFlow
Sources.PrescribedHeatFlow
Thermal.FluidHeatFlow.Examples.
Changed the instance names of components used in the examples to more up-to-date style.


The following existing components have been improved in a backward compatible way:

Modelica.* Parameter declarations, input and output function arguments without description strings improved
by providing meaningful description texts.
Modelica.Blocks.Continuous.
TransferFunction Internal scaling of the controller canonical states introduced in order to enlarge the range of transfer functions where the default relative tolerance of the simulator is sufficient.
Butterworth
CriticalDamping
Documentation improved and plots of the filter characteristics added.
Electrical.Analog.Basic.
EMF New parameter "useSupport" to optionally enable a support connector.
Icons.
TranslationalSensor
RotationalSensor
Removed drawing from the diagram layer (kept drawing only in icon layer),
in order that this icon can be used in situations where components are dragged in the diagram layer.
Math.Vectors.
normalize Implementation changed, so that the result is awalys continuous
(previously, this was not the case for small vectors: normalize(eps,eps)).
Mechanics.MultiBody.
Renamed non-standard keywords defineBranch, defineRoot, definePotentialRoot, isRooted to the standard names:
Connections.branch/.root/.potentialRoot/.isRooted.
Frames Added annotation "Inline=true" to all one-line functions (which should be all inlined).
Mechanics.MultiBody.Parts.
Mounting1D
Rotor1D
BevelGear1D
Changed implementation so that no longer modifiers for connector variables are used,
because this violates the restrictions on "balanced models" of Modelica 3.
Mechanics.Rotational.
InitializeFlange Changed implementation so that counting unknowns and equations is possible without actual values of parameters.
Thermal.FluidHeatFlow.Interfaces.Partials.
TwoPort Introduced parameter Real tapT(final min=0, final max=1)=1
that defines the temperature of the heatPort between inlet and outlet.
StateGraph.
InitialStep
InitialStepWithSignal
Step
StepWithSignal
Changed implementation so that no longer modifiers for output variables are used,
because this violates the restrictions on "balanced models" of Modelica 3.


The following critical errors have been fixed (i.e., errors that can lead to wrong simulation results):

Electrical.Analog.Examples.
CauerLowPassSC Wrong calculation of Capacitor1 both in Rn and Rp corrected (C=clock/R instead of C=clock*R)
Mechanics.MultiBody.Parts.
Rotor1D The 3D reaction torque was not completely correct and gave in some situations a wrong result. This bug should not influence the movement of a multi-body system, but only the constraint torques are sometimes not correct.
Mechanics.Rotational.
ElastoBacklash If the damping torque was too large, the reaction torque could "pull" which is unphysical. The component was newly written by limiting the damping torque in such a case so that "pulling" torques can no longer occur. Furthermore, during initialization the characteristics is made continuous to reduce numerical errors. The relative angle and relative angular velocities are used as states, if possible (StateSelect.prefer), since relative quantities lead usually to better behavior.
Position
Speed
Accelerate
Move
The movement of the flange was wrongly defined as absolute; this is corrected as relative to connector support.
For Accelerate, it was necessary to rename RealInput a to a_ref, as well as the start values phi_start to phi.start and w_start to w.start. The conversion script performs the necessary conversion of existing models automatically.
Media.Interfaces.
PartialSimpleIdealGasMedium Inconsistency in reference temperature corrected. This may give different results for functions:
specificEnthalpy, specificInternalEnergy, specificGibbsEnergy, specificHelmholtzEnergy.
Media.Air.
specificEntropy Small bug in entropy computation of ideal gas mixtures corrected.
Media.IdealGases.Common.MixtureGasNasa
specificEntropy Small bug in entropy computation of ideal gas mixtures corrected.


The following uncritical errors have been fixed (i.e., errors that do not lead to wrong simulation results, but, e.g., units are wrong or errors in documentation):

Blocks.Tables.
CombiTable2D Documentation improved.
Electrica.Digital.Gates
AndGate
NandGate
OrGate
NorGate
XorGate
XnorGate
The number of inputs was not correctly propagated to the included base model.
This gave a translation error, if the number of inputs was changed (and not the default used).
Electrica.Digital.Sources
Pulse Model differently implemented, so that warning message about "cannot properly initialize" is gone.
Mechanics.Rotational.
BearingFriction
Clutch
OneWayClutch
Brake
Gear
Declaration of table parameter changed from table[:,:] to table[:,2].
Modelica.Mechanics.MultiBody.Examples.Loops.Utilities.
GasForce Unit of variable "press" corrected (from Pa to bar)
StateGraph.Examples.
SimpleFriction The internal parameter k is defined and calculated with the appropriate unit.
Thermal.FluidHeatFlow.Interfaces.Partials.
SimpleFriction The internal parameter k is defined and calculated with the appropriate unit.