Upgrade Considerations When Converting Hydraulic to Isothermal Liquid Models

When you use the hydraulicToIsothermalLiquid conversion tool to convert hydraulic blocks to isothermal liquid blocks, you may need to update the fluid properties, block parameters, or blocks in the converted model to ensure that the model functionality does not change.

The hydraulicToIsothermalLiquid conversion tool replaces hydraulic blocks with equivalent isothermal liquid blocks and preserves the parameter values and connections between the blocks, when possible. The tool then generates an HTML conversion report that lists the issues encountered during the conversion process. The goal of the conversion tool is to maintain equivalent numeric behavior, but because isothermal liquid blocks contain features that hydraulic blocks do not have, there is often no one-to-one relationship between the Isothermal Liquid and Hydraulic library blocks. Consequently, you may need to use the conversion report to manually fix these issues. Additionally, 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 How to Upgrade Hydraulic Models.

Subsystems

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. After the conversion process, you can move the new block out of the subsystem and manually reroute the connection lines, if desired.

To remove a subsystem, right-click it and select Subsystem & Model Reference > Expand Subsystem or use the Simulink.BlockDiagram.expandSubsystem function. For example, for a subsystem Subsystem in a model SimscapeModel, the command is

Simulink.BlockDiagram.expandSubsystem('SimscapeModel/Subsystem','CreateArea','Off');

Repeat this process for each subsystem in the model.

Custom Blocks

The conversion tool does not convert custom blocks with hydraulic ports. Use the Interface (H-IL) block to connect these blocks to the converted sections of the model or manually update the custom blocks.

For information on how to rewrite the source code of hydraulic custom components, see Upgrading Custom Hydraulic Blocks to Use the Isothermal Liquid Domain.

Parameter Comments

If a parameter in your Hydraulics (Isothermal) blocks contain comments, the conversion tool may remove % symbols and any comment content. This happens when a parameter is used in a derived parameter. Comments can be manually added again to a converted block parameter.

Fluid Properties

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. If your original model contains a Hydraulic Fluid block, which is available with Simscape™ Fluids™, the tool replaces this block with an Isothermal Liquid Predefined Properties (IL) block.

If the original model does not include a Custom Hydraulic Fluid block or Hydraulic Fluid block, the blocks in this network use the default fluid and the conversion report includes a warning. However, the conversion tool does not return a warning if the model has multiple hydraulic networks, and some do not contain a block specifying fluid properties.

After running the conversion tool, inspect your model for networks 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. If you want the new model to match the original default hydraulic fluid properties, set these 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.

Upgrade Considerations for Simscape Foundation Library Blocks

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 replaces each of these blocks with their equivalent isothermal liquid blocks. 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.

To address this issue, replace all of the blocks with a single Pipe (IL) block and configure it to model dynamic compressibility and fluid inertial effects. This table shows examples of Hydraulic block configurations and the equivalent Pipe (IL) block configurations.

Old Model New Model

Old Model	New Model
	Fluid dynamic compressibility — `Off`
	Fluid dynamic compressibility — `On` Fluid inertia — `Off` Initial liquid pressure — `0.101325 MPa` plus the beginning value of the Pressure (gauge) variable in the Constant Volume Hydraulic Chamber block
	Fluid dynamic compressibility — `On` Fluid inertia — `On` Initial liquid pressure — `0.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)

Fluid dynamic compressibility — Off

Fluid dynamic compressibility — On

Fluid inertia — Off

Initial liquid pressure — 0.101325 MPa plus the beginning value of the Pressure (gauge) variable in the Constant Volume Hydraulic Chamber block

Fluid dynamic compressibility — On

Fluid inertia — On

Initial liquid pressure — 0.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 Hydro-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 library 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.

Upgrade Considerations for Simscape Fluids Blocks

Physical Signal Blocks

During the conversion process, the hydraulicToIsothermalLiquid tool converts some blocks with physical signal inputs in the Hydraulics (Isothermal) library into subsystems that contain physical signal function blocks, such as PS Subtract or PS Add. Physical signal function blocks inherit their units from the input blocks and cannot inherit units of 1. Consequently, the converted model generates a compilation error if the input to the function block is 1.

If there are physical signal blocks providing input with units of 1 to newly-inserted physical signal function blocks, a compilation error may occur. To avoid an error, change the units in existing physical signal blocks to an appropriate unit other than 1. To propagate units through physical signal blocks, check and upgrade your model before conversion with the Upgrade Advisor. See Upgrading Models with Legacy Physical Signal Blocks for more information.

Derived Parameters

The conversion tool creates derived parameters when it creates a new Isothermal Liquid block parameter from a Hydraulics (Isothermal) parameter. For example, the tool may create an area parameter from a user-defined parameter for the diameter. The derived parameter may depend on the block setting that was active during the conversion. If you change the Isothermal Liquid block setting after conversion, the derived parameter may be inaccurate. This is typically true when converting orifice and valve blocks into their Isothermal Liquid equivalents.

If you change the block parameters in the converted model, you can check that the derived parameter has been correctly updated by changing the parameter in the original Hydraulics (Isothermal) block or model, running the conversion tool with the new setting, and comparing the behavior of the two blocks.

For example, in the 2-Way, 3-Way, and 4-Way Directional Valve and Variable Orifice blocks, changing the Model parameterization parameter before conversion in the hydraulic block may result in different derivations of the spool position at the maximum orifice area parameter in the Isothermal Liquid block.

When the Hydraulic (Isothermal) block's Model parameterization parameter is set to By maximum area and opening, the Isothermal Liquid block's Spool position at maximum orifice area parameter is a function of the Hydraulic block's Valve opening offset and Maximum opening parameters. When the Hydraulic (Isothermal) block's Model parameterization parameter is set to Area vs. opening table, the Isothermal Liquid block's Spool position at maximum orifice area parameter is a function of the Hydraulic block's Valve opening offset and Opening vector parameters.

To correct this, manually adjust the expression for the spool position at the maximum opening or change the setting in the Isothermal (Hydraulics) library block and run the conversion tool on the block.

Element Order When Using Tabulated Area or Volumetric Flow Rate Parameterizations

In Hydraulics (Isothermal) blocks where parameterization by area-opening or pressure-flow rate is an option, vector elements can be in any order. However, the vector elements in Isothermal Liquid blocks must be in a specific order.

When an Isothermal Liquid block is parameterized by opening, such as when the Orifice (IL) block Orifice parameterization parameter is Tabulated data - Area vs. control member position, the Orifice area vector elements must be in increasing order. This parameterization corresponds to the Hydraulics (Isothermal) block setting By area vs. opening table.

When an Isothermal Liquid block is parameterized by pressure, such as when the Orifice (IL) block Orifice parameterization parameter is Tabulated data - Volumetric flow rate vs. control member position and pressure drop, the Volumetric flow rate table must have increasing rows and increasing or decreasing columns. This parameterization corresponds to the Hydraulics (Isothermal) block setting By pressure-flow characteristic.

If the vector elements are not in the correct order, simulating the model returns a warning message in the conversion tool HTML report such as:

In the Isothermal Liquid library, Orifice area vector must contain monotonically ascending or descending values. Adjustment of Control member position vector and Orifice area vector may be required.

Pump and Motor Blocks

Nominal density and kinematic viscosity are parameters in the Hydraulics (Isothermal) Variable-Displacement Pressure-Compensated Pump block and in the Fixed-Displacement Motor, Fixed-Displacement Pump, Variable-Displacement Motor, Variable-Displacement Pump blocks when the Modeling Option parameter is set to Analytical or tabulated data and the Leakage and friction parameterization is set to Analytical. The Nominal viscosity and Nominal density parameters affect the Hagen-Poiseuille coefficient. The Isothermal Liquid library blocks use the network fluid properties to define the density and viscosity and calculate the Hagen-Poiseuille with a different expression. You may need to adjust the Isothermal Liquid block Volumetric efficiency at nominal conditions parameter in order to match the functionality of the Hydraulics (Isothermal) block.

For pump blocks, set the Volumetric efficiency at nominal conditions parameter in the Isothermal Liquid block to

$η_{n o m, I L} = 1 - \frac{ν_{n o m, H} ρ_{n o m, H}}{ν ρ} (1 - η_{H}),$

where:

ν_nom,H is the value of the Nominal kinematic viscosity parameter in the Hydraulic (Isothermal) pump block.
ρ_nom,H is the value of the Nominal fluid density parameter in the Hydraulic (Isothermal) pump block.
η_H is the value of the Volumetric efficiency at nominal conditions parameter in the Hydraulic (Isothermal) pump block.
ν is the value of the Kinematic viscosity at atmospheric pressure parameter in the Isothermal Liquid Properties (IL) block.
ρ is the value of the Density at atmospheric pressure (no entrained air) parameter in the Isothermal Liquid Properties (IL) block.

For motor blocks, set the Volumetric efficiency at nominal conditions parameter in the Isothermal Liquid block to

$η_{n o m, I L} = 1 + \frac{ν ρ}{(\frac{1}{η_{H}} - 1) ν_{n o m, H} ρ_{n o m, H}} .$

For an example using these conversions, see Upgrading Hydraulics (Isothermal) Models in Simscape Fluids (Simscape Fluids).