Main Content

Upgrading Hydraulic Models To Use Isothermal Liquid Blocks

In R2020a, Isothermal Liquid blocks were introduced to model hydraulic systems where the working fluid temperature remains constant during simulation. These blocks are intended for the same types of applications as the Hydraulic blocks in the Foundation library, or the Hydraulics (Isothermal) blocks in the Fluids library (which are available with a Simscape™ Fluids™ license). All of the hydraulic blocks in your models continue to work as before. However, Isothermal Liquid library blocks provide improved usability, increased accuracy, and enhanced simulation robustness.

Advantages of Using Isothermal Liquid Blocks

Using Isothermal Liquid library blocks to model isothermal hydraulic systems provides improved usability, increased accuracy, and enhanced simulation robustness:

  • The streamlined library is easier to use because it combines blocks that perform the same function and adds blocks that have improved parameterization options. For example, the Laminar Leakage (IL) block provides a choice of different cross-sectional geometries. Each of the sources can be configured as either controlled or constant, with the Flow Rate Source (IL) block providing the options for generating either mass flow rate or volumetric flow rate. Similarly, the Flow Rate Sensor (IL) block lets you measure mass flow rate, volumetric flow rate, or both. The Pressure Sensor (IL) block provides a choice of built-in measurements (including pressure difference, absolute pressure, or gauge pressure) and does not require additional reference blocks to account for absolute zero.

  • In the Hydraulic library, only certain blocks (the ones with compressibility effect) model density as a function of pressure, while the other blocks use constant density (which is specified as a global parameter of the working fluid). In contrast, all of the blocks in the Isothermal Liquid library account for fluid density being a function of pressure. The Isothermal Liquid library makes it easy to specify your working fluid by selecting the bulk modulus model and the desired option for modeling the amount of entrained air. These selections are then reflected in all of the block equations, which increases the accuracy of the simulation.

  • In the isothermal liquid domain, the Across and Through variables are absolute pressure and mass flow rate (in the hydraulic domain, the variables are gauge pressure and volumetric flow rate). Using mass flow rate as the Through variable (instead of volumetric flow rate) reduces the potential for small errors in mass conservation to accumulate over time due to the conversion between mass and volumetric quantities, and thus results in increased accuracy.

  • Unlike the Hydraulic library blocks, the pipe and actuator blocks in the Isothermal Liquid library account for fluid compressibility by default, which reduces the likelihood of dry nodes and makes the simulation more robust. This also results in improved usability because you do not need to add extra Constant Volume Chamber blocks to your model to mitigate the effect of dry nodes.

  • All block equations in the Isothermal Liquid library have been optimized to provide smooth transitions, reduce zero-crossings, and improve handling of zero flow and flow reversal. These improvements increase simulation robustness.

Upgrade Considerations

The Isothermal Liquid block library is structured similar to other fluid domains, such as the Thermal Liquid library. These libraries have been streamlined to take advantage of the latest Simscape language features, such as conditional port visibility, and to improve block usability. As a result, there is often no one-to-one correspondence between the Isothermal Liquid and Hydraulic library blocks and you cannot easily substitute one for another.

The hydraulicToIsothermalLiquid conversion tool facilitates model upgrades by automatically replacing Hydraulic blocks with the equivalent Isothermal Liquid blocks, while trying to preserve the parameter values and connections between the blocks, where possible. After the conversion process, the tool saves the converted model under a new name and generates an HTML report that lists any issues encountered during the conversion process. You can review the HTML report and manually fix the remaining issues.

When the Isothermal Liquid block port locations are different from the original Hydraulic block, the tool places the new block in a subsystem to minimize rerouting the connection lines in the block diagram. In most cases, the subsystem port locations match the original ports of the Hydraulic block, and therefore the original layout of the block diagram is preserved. After the conversion process, you can move the new block out of the subsystem and manually reroute the connection lines, if desired.

After the upgrade, the simulation results for the original and the converted model might be slightly different. This difference can be more pronounced at higher pressures. You can use the Simulation Data Inspector to compare the results.

You can use the hydraulicToIsothermalLiquid tool to convert any type of a block diagram system, such as a model, subsystem, or library. For more information, see Upgrading Systems with Enabled Library Links, Model References, and Subsystem References.

Fluid Properties

The default fluid properties in the isothermal liquid domain differ from the hydraulic domain. If your original model contains a Custom Hydraulic Fluid block, the conversion tool automatically replaces it with an Isothermal Liquid Properties (IL) block and sets its parameter values to match the original fluid properties.

Similarly, if your model contains a Hydraulic Fluid block, which is available with Simscape Fluids libraries, the tool automatically replaces this block either with a Simscape Fluids Isothermal Liquid Predefined Properties (IL) block (if that block contains a matching predefined fluid) or with an Isothermal Liquid Properties (IL) block, setting its parameter values to match the original fluid properties. For more information, see Upgrading Simscape Fluids Models Containing Hydraulics (Isothermal) Blocks (Simscape Fluids).

If there is no fluid properties block attached to a circuit, the blocks in this circuit use the default fluid. Because the default fluid properties in the isothermal liquid domain differ from the hydraulic domain, the conversion tool issues a warning if there is no Custom Hydraulic Fluid block or Hydraulic Fluid block anywhere in the model. However, the conversion tool does not detect situations where the model has multiple hydraulic circuits, some of which do not contain a block specifying fluid properties.

After running the conversion tool, inspect your model for circuits that do not contain an Isothermal Liquid Properties (IL) or Isothermal Liquid Predefined Properties (IL) block. Add the Isothermal Liquid Properties (IL) block manually and adjust its parameters, as needed. To match the default hydraulic fluid properties, set the following block parameter values:

  • Liquid density at atmospheric pressure (no entrained air): 850 kg/m^3

  • Liquid isothermal bulk modulus at atmospheric pressure (no entrained air): 0.8e9 Pa

  • Kinematic viscosity at atmospheric pressure: 18e-6 m^2/s

  • Use the default values for other block parameters.

Pipes

The Hydraulic Resistive Tube block accounts only for the pressure drop due to the viscous friction force and ignores the inertia and dynamic compressibility effects on the fluid pressure. In hydraulic models, this block is often combined with Constant Volume Hydraulic Chamber and Fluid Inertia blocks to model fluid compressibility and inertia. The conversion tool handles each block individually. However, after running the conversion tool, you can replace the whole group of blocks with a single Pipe (IL) block and configure it to model dynamic compressibility and fluid inertia effects, as needed.

The table shows some examples of Hydraulic block configurations and matching parameterizations of the replacement Pipe (IL) block.

Old ModelNew Model

Fluid dynamic compressibilityOff

Fluid dynamic compressibilityOn

Fluid inertiaOff

Initial liquid pressure0.101325 MPa plus the beginning value of the Pressure (gauge) variable in the Constant Volume Hydraulic Chamber block

Fluid dynamic compressibilityOn

Fluid inertiaOn

Initial liquid pressure0.101325 MPa plus the beginning value of the Pressure (gauge) variable in the Constant Volume Hydraulic Chamber block

Initial mass flow rate from port A to port B — the beginning value of the Flow rate variable in the Fluid Inertia block times fluid density (extracted from the Custom Hydraulic Fluid or Hydraulic Fluid block connected to the circuit)

Translational Mechanical Converter

The direction of the interface force in the Translational Hydro-Mechanical Converter block is the opposite of the force in the Translational Mechanical Converter (IL) block. In the Hydraulic block, the positive direction of the force is from port C to port R, while in the Isothermal Liquid and other fluids libraries, the positive interface force is from port R to port C.

If you are logging this variable, modify your code to change the sign. The name of the variable has also changed, from f in Hydraulic block to interface_force in the Isothermal Liquid block.

Upgrading Your Models

The hydraulicToIsothermalLiquid conversion tool replaces Hydraulic blocks in your model with equivalent Isothermal Liquid blocks.

The table lists the Hydraulic blocks in the Foundation library and the replacement Isothermal Liquid blocks. For information on blocks from the Fluids > Hydraulics (Isothermal) library, see Upgrading Simscape Fluids Models Containing Hydraulics (Isothermal) Blocks (Simscape Fluids).

Block Substitution

Old ModelNew Model

Constant Area Hydraulic Orifice

Local Restriction (IL)

Restriction typeFixed

Constant Volume Hydraulic Chamber

Constant Volume Chamber (IL)

Fluid Inertia

This block does not map directly to Isothermal Liquid libraries. The conversion tool comments the block out. To preserve the diagram layout, the conversion tool places the commented out block in a subsystem and connects the subsystem ports to bypass the block.

The conversion tool also creates a corresponding entry in the Removed Blocks section of the HTML report.

For information on how you can model fluid inertia using the Pipe (IL) block, see Pipes.

Hydraulic Cap

This block does not map to Isothermal Liquid libraries because you no longer need to terminate unconnected conserving ports in your model.

The conversion tool comments the block out, removes the connection line, and sets the Through variable at the port formerly connected to this block to 0.

The conversion tool also creates a corresponding entry in the Removed Blocks section of the HTML report.

If you used the Hydraulic Cap block to set the initial value for the Pressure variable, consider modifying the initial pressure value in the block formerly connected to the Hydraulic Cap block.

Hydraulic Piston Chamber

This block does not map to Isothermal Liquid libraries because you can model fluid compressibility directly in the mechanical converter blocks.

The conversion tool comments the block out and creates a corresponding entry in the Removed Blocks section of the HTML report.

Hydraulic Reference

Reservoir (IL)

Hydraulic Resistive Tube

Pipe (IL)

Infinite Hydraulic Resistance

Infinite Flow Resistance (IL)

Linear Hydraulic Resistance

Laminar Leakage (IL)

Rotational Hydro-Mechanical Converter

Rotational Mechanical Converter (IL)

Translational Hydro-Mechanical Converter

Translational Mechanical Converter (IL)

Variable Area Hydraulic Orifice

Local Restriction (IL)

Restriction typeVariable

Variable Hydraulic Chamber

This block does not map to Isothermal Liquid libraries because you can model fluid compressibility directly in the mechanical converter blocks.

The conversion tool comments the block out and creates a corresponding entry in the Removed Blocks section of the HTML report.

Hydraulic Flow Rate Sensor

Flow Rate Sensor (IL)

Hydraulic Pressure Sensor

Pressure Sensor (IL)

Hydraulic Constant Flow Rate Source

Flow Rate Source (IL)

Source typeConstant

Flow rate typeVolumetric flow rate

Hydraulic Constant Mass Flow Rate Source

Flow Rate Source (IL)

Source typeConstant

Flow rate typeMass flow rate

Hydraulic Constant Pressure Source

Pressure Source (IL)

Source typeConstant

Hydraulic Flow Rate Source

Flow Rate Source (IL)

Source typeControlled

Flow rate typeVolumetric flow rate

Hydraulic Mass Flow Rate Source

Flow Rate Source (IL)

Source typeControlled

Flow rate typeMass flow rate

Hydraulic Pressure Source

Pressure Source (IL)

Source typeControlled

Custom Hydraulic Fluid

Isothermal Liquid Properties (IL)

Broken Connections and Unconverted Blocks

The tool converts the blocks from the Foundation > Hydraulic library and from the Fluids > Hydraulics (Isothermal) library, which is available with Simscape Fluids. However, the tool does not convert custom blocks with hydraulic ports. The tool also does not convert commented out blocks and referenced subsystems.

The Broken Connections section of the HTML report is an indicator of unconverted blocks in your model. Broken connections result if the tool fails to convert a hydraulic block and then tries to connect it to the successfully converted Isothermal Liquid blocks. In this case, the conversion tool highlights the broken connections in the block diagram. The Broken Connections section of the HTML report contains hyperlinks to the Isothermal Liquid blocks with broken connections and a hyperlink to the Interface (H-IL) block. You can use this block to restore the broken connections.

Conversion Messages

The hydraulicToIsothermalLiquid conversion tool tries to preserve the block parameter values, where possible. Sometimes seamless automatic conversion is not possible, and you might have to adjust the parameter values manually or consider using a different modeling option. The table lists examples of conversion messages in the HTML report, explanations, and recommended actions. The actual messages you get might be slightly different depending on the parameter values in your model.

MessageReasonSuggested Actions

Add an Isothermal Liquid Properties (IL) block to specify the liquid properties. Default properties in the Isothermal Liquid domain differ from the Hydraulic domain.

The model does not contain a Custom Hydraulic Fluid block or a Hydraulic Fluid block.

For details and suggested actions, see Fluid Properties.

Beginning value of Flow rate removed. Adjustment of model initial conditions may be required.

The Constant Volume Hydraulic Chamber block in the original model lets you specify initialization priority and target for the Volumetric flow rate into chamber variable. The replacement Constant Volume Chamber (IL) block does not expose this variable for initialization.

If the variable in the original Hydraulic block had the initialization priority of None, the behavior of the new block is the same and no action is necessary.

The conversion tool issues the warning only if the initialization priority is either High or Low.

To see the initialization priority and beginning value for the variable in question, open the block dialog box of the original Hydraulic block and look at the Variables tab.

Use the Variable Viewer to compare the initialization results.

Beginning values of Diameter increase and Flow rate removed. Adjustment of model initial conditions may be required.

The Constant Volume Hydraulic Chamber block in the original model has the Chamber wall type parameter set to Compliant. In this configuration, the block lets you specify initialization priority and targets for the Diameter increase and Volumetric flow rate into chamber variables. The replacement Constant Volume Chamber (IL) block does not expose these variables for initialization.

If the variables in the original Hydraulic block had the initialization priority of None, the behavior of the new block is the same and no action is necessary.

The conversion tool issues the warning only for variables with initialization priority of either High or Low. If only one of the two variables had its initialization priority set to High or Low, then the message mentions only that variable.

To see the initialization priority and beginning value for the variable in question, open the block dialog box of the original Hydraulic block and look at the Variables tab.

Use the Variable Viewer to compare the initialization results.

Beginning values of Flow rate and Pressure differential removed. Adjustment of model initial conditions may be required.

Several Hydraulic blocks, such as orifices or hydro-mechanical converters, have the Variables tab, where you can specify initialization priority and targets for the Flow rate and Pressure differential variables. The equivalent Isothermal Liquid blocks do not expose these variables for initialization.

If the variables in the original Hydraulic block had the initialization priority of None, the behavior of the new block is the same and no action is necessary.

The conversion tool issues the warning only for variables with initialization priority of either High or Low. If only one of the two variables had its initialization priority set to High or Low, then the message mentions only that variable.

To see the initialization priority and beginning value for the variable in question, open the block dialog box of the original Hydraulic block and look at the Variables tab.

Use the Variable Viewer to compare the initialization results.

Block uses Dead volume of 1e-4 m^3. Adjustment of Dead volume may be required.

The Rotational Hydro-Mechanical Converter or Translational Hydro-Mechanical Converter block in the original model has the Compressibility parameter set to Off. When compressibility is off, hydro-mechanical converters do not account for liquid volume and do not expose the Dead volume parameter. The equivalent Isothermal Liquid converter blocks log liquid volume even when compressibility is off.

The conversion tool sets the Dead volume parameter in the replacement Isothermal Liquid block to the same value as in the original Hydraulic block. (The original Hydraulic block used this parameter only with compressibility on.)

The tool also prints the parameter value, for your convenience. Adjust this value, if desired.

Block uses Interface initial displacement of 0 m. Adjustment of Interface initial displacement may be required.

The Translational Hydro-Mechanical Converter block in the original model has the Compressibility parameter set to Off. Hydraulic translational converters expose the Piston initial position parameter only when compressibility is on. The equivalent Isothermal Liquid converter blocks let you specify initial displacement of the interface even when compressibility is off.

The conversion tool sets the Interface initial displacement parameter in the replacement Isothermal Liquid block to the value of the Piston initial position parameter in the original Hydraulic block (even though this parameter was not used with compressibility off.)

The tool also prints the parameter value for your convenience. Adjust this value, if desired.

Block uses Interface initial rotation of 0 rad. Adjustment of Interface initial rotation may be required.

The Rotational Hydro-Mechanical Converter block in the original model has the Compressibility parameter set to Off. Hydraulic rotational converters expose the Shaft initial angle parameter only when compressibility is on. The equivalent Isothermal Liquid converter blocks let you specify initial rotation of the interface even when compressibility is off.

The conversion tool sets the Interface initial rotation parameter in the replacement Isothermal Liquid block to the value of the Shaft initial angle parameter in the original Hydraulic block (even though this parameter was not used with compressibility off.)

The tool also prints the parameter value for your convenience. Adjust this value, if desired.

Chamber specification set to rigid. To model flexible volume, consider using the Simscape Fluids Pipe (IL) block.

The Constant Volume Hydraulic Chamber block in the original model has the Chamber wall type parameter set to Compliant. The replacement Constant Volume Chamber (IL) block does not have this option.

If you have a Simscape Fluids license, you can use the Pipe (IL) block from the Fluids > Isothermal Liquid > Pipes & Fittings library as a replacement.

Consider adjusting the initial pressure in a previously connected block.

The Hydraulic Cap block in the original model has been removed.

For details and suggested actions, see Block Substitution.

Consider modeling fluid compressibility with a Translational Mechanical Converter (IL) block.

The Variable Hydraulic Chamber or Hydraulic Piston Chamber block in the original model has been removed.

For details and suggested actions, see Block Substitution.

Consider modeling fluid inertia with a Pipe (IL) block.

The Fluid Inertia block in the original model has been removed.

For details and suggested actions, see Block Substitution.

Critical Reynolds number set to 150.

The Constant Area Hydraulic Orifice or Variable Area Hydraulic Orifice block in the original model has the Laminar transition specification parameter set to Pressure ratio. These Hydraulic blocks have two options for specifying the transition between the laminar and turbulent regime: by pressure ratio or by critical Reynolds number. The replacement Local Restriction (IL) block does not have the pressure ratio option.

The Local Restriction (IL) block specifies the transition between the laminar and turbulent regime by the critical Reynolds number, and the conversion tool sets the default value of 150 for the Critical Reynolds number parameter.

If the original Hydraulic block used the default Laminar flow pressure ratio parameter value of 0.999, no action is necessary.

If the Laminar flow pressure ratio parameter value in the original block was significantly different, you might need to adjust the Critical Reynolds number parameter value in the replacement block.

Maximum restriction area set to 1e10 m^2.

The Variable Area Hydraulic Orifice block does not have a parameter that specifies the maximum area, the block assumes that the maximum area is inf. The replacement Local Restriction (IL) block, with Restriction type set to Variable, requires a Maximum restriction area parameter value less than inf.

The conversion tool sets the Maximum restriction area parameter in the replacement Local Restriction (IL) block to an arbitrary large value, 1e10 m^2.

Adjust this value, if desired.

Original block had Specific heat ratio of 1.4. Set Air polytropic index to this value in an Isothermal Liquid Properties (IL) block.

Several Hydraulic blocks, such as chambers or hydro-mechanical converters, have a Specific heat ratio parameter. In the isothermal liquid domain, all of the fluid properties are defined in the Isothermal Liquid Properties (IL) block.

The conversion tool prints the value of the Specific heat ratio parameter in the original block for your convenience. Open the Isothermal Liquid Properties (IL) block connected to the circuit and set its Air polytropic index parameter to this value.

Upgrading Systems with Enabled Library Links, Model References, and Subsystem References

You can use the hydraulicToIsothermalLiquid tool to convert any type of a block diagram system, such as a model, subsystem, or library. However, the tool appends _converted to the name of the original file, to avoid overriding original files and allow comparison between the original and converted files. As a result, if you convert a model that contains hydraulic blocks from custom Simulink® libraries, or referenced models or subsystems with hydraulic blocks, converting these libraries and subsystems is not sufficient because the converted model still points to the original libraries, models, and subsystems.

If your model contains references or links to other libraries, models, or subsystems that also need to be converted, then the following approach is recommended:

  1. Use the hydraulicToIsothermalLiquid conversion tool on each file.

  2. In each converted file, find any model references, subsystem references, and enabled library links. Rename them to point to the corresponding converted model, subsystem, or library:

    • For a block with a library link, update the ReferenceBlock parameter.

    • For a model reference, update the ModelFile parameter.

    • For a subsystem reference, update the ReferencedSubsystem parameter.

    You can do this programmatically by using find_system and set_param.

  3. In the HTML report generated for each system, use the Broken Connections section to find and repair broken links.

  4. Compare the simulation results of the converted model to the original model to ensure that the results are as expected. In the HTML report, investigate the messages in the Removed Blocks and Parameter Warnings sections. The messages in these sections indicate whether behavior changes are expected, and suggest appropriate actions.

  5. Once satisfied that the converted systems behave as expected, change the system names back to the original ones, by removing _converted. It is recommended that you do this step after the previous steps have been completed because Simulink software does not let you load two different systems with the same name at the same time.

An alternative approach is to convert block diagram systems piece-by-piece, using the Interface (H-IL) block to connect the converted parts of the block diagram to any unconverted libraries or subsystems. Then, once each of the libraries, referenced models, and referenced subsystems is also converted and verified, remove _converted from its name, remove the Interface (H-IL) blocks and restore the broken connections.

See Also

| |

Related Topics