Upgrading Hydraulics (Isothermal) Models in Simscape Fluids

Learn how to use the hydraulicToIsothermalLiquid tool to upgrade Hydraulics (Isothermal) models. You can convert multiple models at the same time.

The blocks in the Isothermal Liquid library account for density as a function of pressure, and pipe and actuator blocks account for compressibility by default. As a result, expect some differences between a model that uses Hydraulics (Isothermal) library blocks and a converted model when compressibility effects play a significant role due to the treatment of conservation equations in the volumetric-flow-rate-based and mass-flow-rate-based libraries.

These examples show how to run the conversion tool, respond to warning messages, and compare and check converted models with the Simulation Data Inspector.

Automatic Conversion

This example converts the Diesel Engine In-Line Injection System model and requires minimal manual adjustments.

1. Open the Diesel Engine In-Line Injection System model by entering openExample('simscapefluids/DieselEngineInLineInjectionSystemHExample') at the MATLAB command line.

2. Enable logging by clicking the signal line connected to the Scope block and clicking Log Signals on the Simulation tab.

3. Simulate the model.

4. On the Simulation tab, click Data Inspector.

5. To see one of the logged flow rates, expand Mux:1 and select Mux:1(1) to see the outlet flow rate in the Injector Pump1 subsystem.

6. Convert the blocks in the model to the isothermal liquid library. At the command prompt, enter hydraulicToIsothermalLiquid('DieselEngineInLineInjectionSystemH').

7. The conversion report, DieselEngineInLineInjectionSystemH_converted.html, opens when the model conversion completes. The report includes three types of warning messages:

   • Predefined fluid has been reparameterized. Behavior change not expected at most temperatures.

     This message indicates that the conversion process redefined the fluid for the Isothermal Liquid library in the Fuel Properties block in DieselEngineInLineInjectionSystemH_converted differently, but no specific parameter requires user input.

   • Critical Reynolds number set to 150. Behavior change not expected.

     The conversion process converted the parameter that indicates flow regime to the Critical Reynolds number parameter. This parameter has a default value of 150. You do not need to adjust anything in the converted model.

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

     This message indicates that the conversion changed the value of the specific heat ratio parameter in the Fuel Properties block.

8. To address the message in the report, in the DieselEngineInLineInjectionSystemH_converted model, open the Fuel Properties block. In the Entrained Air section, set the Air polytropic index parameter to 1.4

9. Run DieselEngineInLineInjectionSystemH_converted.

10. Open the Simulation Data Inspector and select Compare in the left pane. Set Baseline to DieselEngineInLineInjectionSystemH. Set Compare to to DieselEngineInLineInjectionSystemH_converted.

11. Click More. Under Global Tolerances, set Absolute to 1-e5. Set Time to 1e-4.

12. Click Compare. In the left pane, the four green check marks next to the four Mux signals show that the results of the models agree within the specified tolerances.

Conversion with Manual Adjustments

This example uses a modified dual counterbalance valve model. This conversion requires more manual adjustment steps.

1. Open the dual counterbalance valve model by entering sh_HtoIL_dual_counterbalance_start at the MATLAB command line. This model represents a modified dual counterbalance valve. Data logging for the pump angular velocity and cylinder position is already enabled in this model.

2. Save the model as sh_HtoIL_dual_counterbalance_hydro_start in a location where you have write permissions.

3. Set the MATLAB Current Folder to this location.

4. Run the model.

5. Convert the blocks in the model to the isothermal liquid library. At the command line, enter hydraulicToIsothermalLiquid('sh_HtoIL_dual_counterbalance_hydro_start').

6. Run the converted model, sh_HtoIL_dual_counterbalance_hydro_start_converted.

7. The simulation returns the error: Invalid use of -. At least one of the operands must be scalar or the operands must be the same size. The units of the operands must be commensurate. Click the hyperlink below the Caused by message to navigate to the PS Subtract block.

   In the Explorer Bar, click Pipe A to see the PS Constant blocks that are the inputs to the PS Subtract block.

   The two PS Constant blocks attached to the PS Subtract block have different units. The signal from the B Elevation block to el_B has units of 1, while the signal from the A Elevation block to el_A has units of m. In the B Elevation block, change the units for Constant to m.

8. Run the model.

9. In the Simulation tab, click Data Inspector to compare the pump angular velocity and cylinder position between the two models.

   Select Compare in the left pane. Set Baseline to sh_HtoIL_dual_counterbalance_hydro_start. Set Compare to to sh_HtoIL_dual_counterbalance_hydro_start_converted.

10. Click More. Under Global Tolerances set Absolute and Relative to 0.05.

11. Click Compare. Notice that the Cylinder Position signal agrees, but the Pump Rotational Velocity signal does not. When you convert a model from the Hydraulic to the Isothermal Liquid domain, the model may show some discrepancies in behavior due to how the isothermal liquid blocks model compressibility and behave in off-design conditions. Addressing the messages in the warning report may reduce discrepancies.

12. Check the conversion report, sh_HtoIL_dual_counterbalance_hydro_start_converted.html. Some messages listed in the report do not require any changes in the converted model:

    • Critical Reynolds number set to 150. Behavior change not expected.

      The conversion changed the parameter that indicates flow regime to the Critical Reynolds number parameter. This parameter has a default value of 150. You do not need to adjust the converted model.

    • B-T Orifice reparameterized.

      After conversion, the directional valves in the Isothermal Liquid library that open in the neutral spool position switch from two orifices in series to one orifice between ports. This change results in a modification to the orifice area when approaching the orifice maximum area, as shown below. You do not need to modify the model.

      

      Note that this warning applies to orifices in the 4-Way 3-Position Directional Valve (IL) that open in the neutral spool position. This warning does not affect the P-B Orifice, which opens only in the positive and negative spool positions.

    • Pressure losses due to kinetic energy change added. Adjustment of Expansion correction factor and Contraction correction factor may be required.

      If the area change is large, which means that the pressure change due to the second term and power adjustment are within the tolerance of the model, you do not need to adjust the model. If the contraction is small, then you can tune the model by adjusting the smaller or both of the port areas. In the Hydraulics (Isothermal) block, the pressure loss is modeled as

      $$\Delta p\approx \frac{K_{PC}{\dot{m}}^2}{4\rho A_{small}^2}{\left(1-\frac{A_{small}}{A_{large}}\right)}^{0.75}.$$

      In the Isothermal Liquid block, the pressure loss is

      $$\Delta p\approx \frac{K_{contraction}{\dot{m}}^2}{4\overline{\rho }{A}_{small}^2}\left(1-\frac{A_{small}}{A_{large}}\right)+\frac{{\dot{m}}^2}{2\overline{\rho }{A}_{small}^2}\left(1-\frac{A_{small}}{A_{large}}\right).$$

      In this model, you do not need to adjust these values.

    • Contraction loss coefficient reformulated. Adjustment of Contraction correction factor may be required.

      The Contraction correction factor parameter is similar to the Expansion correction factor parameter. You only need to adjust the parameter value if the area change is large. In this model, you do not need to adjust these values.

13. The remaining messages in sh_HtoIL_dual_counterbalance_hydro_start_converted.html require adjustments to the converted model:

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

      In the Fluid Properties block, in the Entrained Air section, set the Air polytropic index parameter to 1.4.

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

      This message indicates that you cannot set the priority and target value of the specified block. Set the priority and target of a variable in an adjacent block.

      • In sh_HtoIL_dual_counterbalance_hydro_start, check the initial conditions of the Fixed Orifice A block. In the block dialog, under the Initial targets section, the flow rate is 0 m^3/s with Priority set to High.

      • In sh_HtoIL_dual_counterbalance_hydro_start_converted, open the Variable Viewer to check the initial conditions of the Fixed Orifice A. The mass flow rate initializes to a nonzero value.

        

      • In sh_HtoIL_dual_counterbalance_hydro_start, open the Variable Viewer. The initial value of the pressure for the Constant Volume Hydraulic Chamber is 17010.8 Pa.

        

      • Set the converted model to match this value. In the Pipe A subsystem of sh_HtoIL_dual_counterbalance_hydro_start_converted, in the Constant Volume Hydraulic Chamber dialog box, under the Initial targets section, set the Pressure of liquid volume parameter Priority to High and Value to 17010.8 + 101325 Pa.

      • Run the converted model. The Variable Viewer shows that the mass flow rate in the Fixed Orifice A block starts at a value of -1.6e-4 kg/s. This value is not a perfect match to 0 kg/s, but it is closer than before.

        

    • Interpolation method changed to Linear. Additional elements in the Reynolds number vector, Contraction loss coefficient vector, and Expansion loss coefficient vector may be required.

      You can add additional elements to the Reynolds number and loss coefficient vectors in the command line by using the interp1 function.

      In the hydraulics model, the workspace variable for the Reynolds number vector parameter is defined as Re_vec and the Loss coefficient vector parameter is defined as loss_coeff_vec. In the MATLAB command window, enter:

      Re_vec_smooth = -6000:100:6000;
      loss_coeff_vec_smooth = interp1(Re_vec, loss_coeff_vec, Re_vec_smooth, 'makima', 'extrap');

      In the Pipe A subsystem, replace Re_vec with Re_vec_smooth and loss_coeff_vec with loss_coeff_vec_smooth in the Area Change B block dialog:

      • Set the Reynolds number vector parameter to Re_vec_smooth(Re_vec_smooth>0).

      • Set the Contraction loss coefficient vector parameter to [interp1( -fliplr(Re_vec_smooth(Re_vec_smooth<0)), fliplr(loss_coeff_vec_smooth(Re_vec_smooth<0)), Re_vec_smooth(Re_vec_smooth>0), 'linear', loss_coeff_vec_smooth(1))].

      • Set the Expansion loss coefficient vector parameter to loss_coeff_vec_smooth(Re_vec_smooth>0).

      The command extrapolates the data set linearly to Re = 6000 and applies a smooth interpolation method the next time the simulation runs.

    • Only elements greater than or equal to 0 retained in Reynolds number vector. Expansion loss coefficient values mapped to these Reynolds numbers. Adjustment of Reynolds number vector, Contraction loss coefficient vector, and Expansion loss coefficient vector may be required.

      The Reynolds number vector in the original Area Change B block has both negative and positive Reynolds numbers, [-6000 -4000 -1000 -200 -50 -30 -20 -10 -1 1 20 40 100 500 2000 5000], but the converted Area Change B block only preserves positive Reynolds numbers. The converted Area Change B block in the Pipe A subsystem symmetrically extends the positive elements of the user-provided Reynolds number vector to negative Reynolds numbers. The converted block also separates and extends the loss coefficient vector to individual expansion and contraction loss coefficient vectors. To match the original model behavior, you need to extend the data set to Re = 6000 in the base workspace. The commands in the previous step also addressed this warning.

    • Nominal fluid density and kinematic viscosity removed. Pump uses network fluid properties. Adjustment of Volumetric efficiency at nominal conditions may be required.

      In the Hydraulics (Isothermal) library, you can define density and viscosity specifically for pump or motor blocks. Isothermal Liquid blocks use network properties to model these values. To account for this change, adjust the Volumetric efficiency at nominal conditions parameter in the Fixed-Displacement Pump (IL) block:

      • In the Fixed-Displacement Pump (IL) dialog, set the Volumetric efficiency at nominal conditions parameter to 0.957, which is determined using the formula

        $${\eta }_{IL,equiv}=1-\frac{{\nu }_{H,nom}{\rho }_{H,nom}}{{\nu }_{IL}{\rho }_{IL}}\left(1-{\eta }_H\right),$$

        where:

        • ν_H,nom is the value of the Nominal kinematic viscosity parameter in the Fixed-Displacement Pump block.

        • ρ_H,nom is the value of the Nominal fluid density parameter in the Fixed-Displacement Pump block.

        • η_H is the value of the Volumetric efficiency at nominal conditions parameter in the Fixed-Displacement Pump block.

        • ν_IL is the value of the Kinematic viscosity at atmospheric pressure parameter in the Isothermal Liquid Properties (IL) block.

        • ρ_IL is the value of the Density at atmospheric pressure (no entrained air) parameter in the Isothermal Liquid Properties (IL) block.

14. Save and run sh_HtoIL_dual_counterbalance_hydro_converted.

To see a model that contains all of the post-conversion updates, open sh_HtoIL_dual_counterbalance_end, which includes all post-conversion updates. Inspect the model signals with the Simulation Data Inspector. The Pump Rotational Velocity signals are now within the tolerance for the majority of the time. There are still some expected discrepancies when fast dynamics occur.

Conversion for Models that Include Fluid Dynamic Compressibility

Unlike the Hydraulics (Isothermal) library, all blocks in the Isothermal Liquid library account for density as a function of pressure. In some converted models, this can cause diverging results, which this example illustrates.

1. Open the hydraulic orifice model by entering ssc_HtoIL_orifice at the command line.

2. Save the model as ssc_HtoIL_hydro.mdl to a location where you have write permissions.

3. Set the MATLAB Current Folder to this location. The converted model and the conversion report will be saved here.

4. Run the model.

5. Convert the blocks in the model to the isothermal liquid library. At the command prompt, enter hydraulicToIsothermalLiquid('ssc_HtoIL_hydro').

6. Run the converted model.

7. Open the Simulation Data Inspector and select Compare in the left pane. Set Baseline to ssc_HtoIL_hydro. Set Compare to to ssc_HtoIL_hydro_converted.

8. Click More. Under Global Tolerances set Absolute, Relative, and Time to 0.01.

9. Click Compare.

   As the applied pressure increases, the mass flow rates in the Hydraulics (Isothermal) and Isothermal Liquid models diverge.

   

   This divergence is due to the fact that density is constant in the Hydraulics (Isothermal) block and varies as a function of pressure in the Isothermal Liquid block.

   

Depending on your application, your converted model may require tuning to account for density changes due to changes in pressure or temperature.