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 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 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 Model	New Model
Constant Area Hydraulic Orifice	Local Restriction (IL) Restriction type — `Fixed`
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 type — `Variable`
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 type — `Constant` Flow rate type — `Volumetric flow rate`
Hydraulic Constant Mass Flow Rate Source	Flow Rate Source (IL) Source type — `Constant` Flow rate type — `Mass flow rate`
Hydraulic Constant Pressure Source	Pressure Source (IL) Source type — `Constant`
Hydraulic Flow Rate Source	Flow Rate Source (IL) Source type — `Controlled` Flow rate type — `Volumetric flow rate`
Hydraulic Mass Flow Rate Source	Flow Rate Source (IL) Source type — `Controlled` Flow rate type — `Mass flow rate`
Hydraulic Pressure Source	Pressure Source (IL) Source type — `Controlled`
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.

Message	Reason	Suggested 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 dialog box for the original Hydraulic block and look at the Initial Targets section. 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 dialog box for the original Hydraulic block and look at the Initial Targets section. 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 Initial Targets section, 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 dialog box for the original Hydraulic block and look at the Initial Targets section. 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. When you convert models that contain hydraulic blocks from custom Simulink^® libraries, or referenced models or subsystems with hydraulic blocks, it is important to preserve the links between the files, so that the converted models point to the converted libraries, referenced models, and subsystems. To preserve the links during the conversion, convert these files together, by supplying either a list of files or a top folder containing these files as an input argument to the hydraulicToIsothermalLiquid conversion tool.

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:

Use one of these syntaxes for the hydraulicToIsothermalLiquid conversion tool to convert the files together:
- convertedFiles = hydraulicToIsothermalLiquid(oldfiles) — Convert all files in the oldfiles list and return the names of converted files in convertedFiles. oldfiles is a cell array of file names, such as {'file1';'file2';'file3'}. If a file in the list does not contain hydraulic blocks and does not refer to a file listed in oldfiles that contains hydraulic blocks, it is not converted.
- convertedFiles = hydraulicToIsothermalLiquid(topfolder) — Convert all files in topfolder and its subfolders that are on the MATLAB^® path, if the files contain hydraulic blocks. If a file does not contain hydraulic blocks and does not refer to a file under topfolder that contains hydraulic blocks, it is not converted. topfolder is the path name of the top folder containing block diagram systems to convert, specified as a character vector or string scalar, such as 'MyLibraries'. convertedFiles returns the names of converted files in a cell array of character vectors.
In the common HTML report generated during the conversion, use the Broken Connections section to find and investigate broken links, if any. When you convert the files together, the links between the files and the connections within files are preserved. Broken connections might indicate that you forgot to include a reference model or library in the conversion. In this case, either repair the link manually or rerun the conversion process with the expanded list of files.
Compare the simulation results of the converted models to the original models 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.
Once satisfied that the converted systems behave as expected, change the system names back to the original ones:
```
finalFiles = hydraulicToIsothermalLiquidPostProcess(convertedFiles)
```
This function overwrites the original files by removing the _converted suffix from the file names and from the links between the files. For more information, see hydraulicToIsothermalLiquidPostProcess.

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.