Main Content

hydraulicToIsothermalLiquid

Upgrade hydraulic block diagram system to use isothermal liquid blocks

Since R2020a

collapse all in page

Syntax

newfile = hydraulicToIsothermalLiquid(oldfile,newpath)
newfiles = hydraulicToIsothermalLiquid(oldfiles)
newfiles = hydraulicToIsothermalLiquid(toppath)
newfiles = hydraulicToIsothermalLiquid(___,oldcustomblocks,newcustomblocks)

Description

newfile = hydraulicToIsothermalLiquid(oldfile,newpath) replaces blocks from the Foundation > Hydraulic library in the specified block diagram system, oldfile, with equivalent Isothermal Liquid library blocks, while trying to preserve the parameter values and connections between the blocks, where possible. If you have a Simscape™ Fluids™ license, this tool also replaces blocks from the Fluids > Hydraulics (Isothermal) library with equivalent blocks from the Fluids > Isothermal Liquid and Foundation > Isothermal Liquid libraries. oldfile can be a model, subsystem, or library.

Isothermal Liquid block libraries are structured similar to other fluid domains, such as Thermal Liquid, and often there is no one-to-one correspondence between the Isothermal Liquid and Hydraulic library blocks. The conversion tool lists all the issues encountered during the conversion in an HTML report, saves both the report and the converted block diagram system in the location specified by newpath, and returns the name of the converted system, newfile.

Both the newfile and the newpath arguments are optional. If you omit the newpath argument, you must have write permissions for your current working folder, because the tool then saves the converted system and the report in the current folder.

The new file is based on the last saved version of the old file. That is, if you modify the original block diagram system and do not save it before using the conversion tool, the modifications are not reflected in the new system. It is also good practice to make sure that the original block diagram system compiles without issues before using the conversion tool.

For more information on upgrade considerations and process, see Upgrading Hydraulic Models to Use Isothermal Liquid Blocks.

example

newfiles = hydraulicToIsothermalLiquid(oldfiles) converts a list of files, oldfiles, where each of the files can be a model, subsystem, or library. When you convert a list of files, the conversion tool preserves the links between the converted files in the list. Use this syntax to convert models containing references or links to other libraries, models, or subsystems.

If a file listed in oldfiles contains blocks from the Foundation > Hydraulic library or Fluids > Hydraulics (Isothermal) library, the tool replaces them with equivalent Isothermal Liquid library blocks, appends _converted to the name of the original file, and saves each converted file in the same folder as the original file. If a file does not contain hydraulic blocks and does not refer to a file listed in oldfiles that contains hydraulic blocks, the tool leaves this file unchanged. The tool returns the list of converted file names, newfiles, and saves the conversion report at the location of the first file listed in oldfiles. The conversion report, named HtoIL_report, lists all the issues encountered during the conversion of all the files in the oldfiles list.

example

newfiles = hydraulicToIsothermalLiquid(toppath) converts all the models, subsystems, and libraries in the folder toppath and its subfolders, while preserving the links between the converted files in the list. Use this syntax to convert custom libraries and other models containing references or links to other libraries, models, or subsystems.

Both toppath and its subfolders must be on the MATLAB® path. If a model, subsystem, or library contains blocks from the Foundation > Hydraulic library or Fluids > Hydraulics (Isothermal) library, the tool replaces them with equivalent Isothermal Liquid library blocks, appends _converted to the name of the original file, and saves each converted file in the same folder as the original file. If a file does not contain hydraulic blocks and does not refer to a file in toppath folder hierarchy that contains hydraulic blocks, the tool leaves this file unchanged. The tool returns the list of converted file names, newfiles, and saves the conversion report, named HtoIL_report, in the toppath folder.

example

newfiles = hydraulicToIsothermalLiquid(___,oldcustomblocks,newcustomblocks) replaces custom hydraulic blocks listed in oldcustomblocks with corresponding isothermal liquid blocks, newcustomblocks. For any of the input argument combinations in the previous syntaxes, specify two cell arrays of custom block names after all the other input arguments. Use this syntax to convert models containing customized hydraulic blocks, such as masked library blocks or custom blocks written in Simscape language.

Before you can use this syntax, prepare the equivalent isothermal liquid version of the customized blocks:

  • For custom library blocks and subsystems that contain blocks from the Foundation > Hydraulic library or Fluids > Hydraulics (Isothermal) library, run the conversion tool on these custom libraries.

  • For custom hydraulic blocks written in Simscape language, manually create equivalent versions of these blocks that use the isothermal liquid domain.

If, during conversion, the tool encounters a block listed in oldcustomblocks, then the tool replaces that block with the equivalent block listed in newcustomblocks. The two cell arrays, oldcustomblocks and newcustomblocks, must have the same number of elements, each element corresponding to a block name. The respective blocks listed in each array must have the same number of ports, matching port order, and the same programmatic parameter names.

Examples

collapse all

This example shows how to use the conversion tool on a model containing Hydraulic blocks. The tool generates a converted model and an HTML report. The next example, Clean Up Model After Conversion, shows how you can use the HTML report to review and fix the issues encountered by the conversion tool.

Open the Hydraulic Actuator with Analog Position Controller example model:

openExample('simscape/HydraulicActuatorWithAnalogControlHExample')

This example model contains blocks from Hydraulic libraries.

Convert the model to replace Hydraulic library blocks with the equivalent blocks from the Isothermal Liquid library:

hydraulicToIsothermalLiquid(bdroot)

ans =

  1×1 cell array

    {'HydraulicActuatorWithAnalogControlH_converted'}

The conversion tool forms the new model name by appending _converted to the name of the original model. Because you did not specify the newpath argument, the conversion tool saves the HydraulicActuatorWithAnalogControlH_converted model in the current folder.

The tool also generates an HTML report and saves it in the current folder. The report lists any issues encountered during the conversion process.

Review the HTML report and manually fix the remaining issues. In this example, the converted model does not contain broken connections or removed blocks, but the conversion tool generated several parameter warnings that require your attention. For more information, see Clean Up Model After Conversion.

In the previous example, Convert Model to Use Isothermal Liquid Blocks, you used the conversion tool on the HydraulicActuatorWithAnalogControlH model. The tool generated a converted model, HydraulicActuatorWithAnalogControlH_converted, and an HTML report. In this example, you will use the HTML report to review and fix the issues encountered by the conversion tool.

For a listing of conversion messages and suggested actions to address them, see Conversion Messages After Converting Hydraulic to Isothermal Liquid Models. For each message, clicking a link in the Block column of the HTML report opens the appropriate subsystem, as necessary, and highlights the block that generated the message.

The first two messages in the HTML report refer to the two chambers of the Hydraulic Actuator subsystem. In the original model, each of these chambers was implemented by a Translational Hydro-Mechanical Converter block. The conversion tool replaced each of these blocks with a Translational Mechanical Converter (IL) block.

The Translational Hydro-Mechanical Converter blocks in the original model had a Specific heat ratio parameter, but 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: Original block had Specific heat ratio of 1.4. Set Air polytropic index to this value in an Isothermal Liquid Properties (IL) block.

Open the Isothermal Liquid Properties (IL) block in the converted model and set its Air polytropic index parameter to 1.4.

After thus addressing the first two conversion messages, click the third link in the Block column of the HTML report.

The tool looks under the mask of the Spool Valve block and highlights the Orifice PA subsystem.

In the original model, HydraulicActuatorWithAnalogControlH, look under the mask of the Spool Valve block.

Orifice PA is one of four Variable Area Hydraulic Orifice blocks that comprise the valve, and each of these blocks has similar conversion messages. The manual cleanup process for each of these blocks is also similar.

Double-click the Orifice PA block in the original model to see its parameters.

The conversion tool replaced each Variable Area Hydraulic Orifice block with a Local Restriction (IL) block. (For more information, see Block Substitutions for Foundation Library Hydraulic Blocks.) Because the port locations for these blocks are different, the conversion tool placed each of the Local Restriction (IL) blocks in a subsystem to preserve the diagram layout.

Double-click the Orifice PA subsystem in the converted model, and then the Orifice PA block inside it, to see its parameters.

The first conversion message for the Orifice PA block, Critical Reynolds number set to 150, stems from the fact that the original Variable Area Hydraulic Orifice block had the Laminar transition specification parameter set to Pressure ratio. The replacement Local Restriction (IL) block can specify the transition between the laminar and turbulent regime only by the critical Reynolds number, and the conversion tool sets the Critical Reynolds number parameter to its default value of 150. Because the Variable Area Hydraulic Orifice block in the original model used the default Laminar flow pressure ratio parameter value of 0.999, no action is necessary.

The second conversion message for the Orifice PA block, Maximum restriction area set to 1e10 m^2, stems from the fact that the original Variable Area Hydraulic Orifice block assumed an infinitely large maximum opening area, while 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. No action is necessary, but you can adjust this value to match the data sheet for your model, if desired.

The rest of the conversion messages refer to the other three orifices and also say that the behavior change is not expected. You can inspect these three blocks in the original model in a similar way, to verify that no action is necessary.

At this point, after you addressed all the conversion messages, the required model cleanup is complete. You can compare the simulation results of the original and the converted model to make sure they are the same. You can also perform further cosmetic cleanup, if desired. For example, you can move the converted blocks that had changes to their port placement out of subsystems and manually reroute the connection lines.

To see an example of this model after conversion and cleanup, open the Hydraulic Actuator with Analog Position Controller example model in the Isothermal Liquid domain:

openExample('simscape/HydraulicActuatorWithAnalogControlExample')

Compare this model with the original model, HydraulicActuatorWithAnalogControlH, and the converted model generated by the tool, HydraulicActuatorWithAnalogControlH_converted.

This example shows how you can convert models together with their referenced models, subsystems, and linked libraries, and preserve the links between the converted files.

Consider a model, for the purposes of this example named modelWithLink, that contains some hydraulic blocks and a referenced model, referenceModel, which also contains hydraulic blocks. referenceModel is located in a separate folder, Reference Systems, which is on the MATLAB path.

Convert the modelWithLink model together with the referenced model, by specifying their names in a file list:

convertedFiles = hydraulicToIsothermalLiquid({'modelWithLink' 'referenceModel'})

convertedFiles =

  2×1 cell array

    {'modelWithLink_converted' }
    {'referenceModel_converted'}

The conversion tool forms the new model name by appending _converted to the name of the original model and saves each converted model in the same folder as the original one.

Notice that the converted model, modelWithLink_converted, now has isothermal liquid blocks and that it now links to the converted reference model, referenceModel_converted, which also has isothermal liquid blocks.

The tool also generates a common conversion report named HtoIL_report and saves it at the location of the first file listed in the oldfiles input argument. In this case, the first file is modelWithLink, therefore the report is saved in the same folder as this file. The report lists the conversion issues for all files in the oldfiles list.

Review the HTML report and manually fix the remaining issues.

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, you can use the hydraulicToIsothermalLiquidPostProcess function to restore the original file names: 

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.

This example shows how you can specify a path to the top-level folder, for the conversion tool to process all the files in this top-level folder and its subfolders. The tool converts all the files that contain hydraulic blocks, while preserving the links between them, and returns the list of converted files. If a file does not contain hydraulic blocks, the tool leaves it unchanged.

Consider a folder, named in this example topFolder for clarity, that contains subfolders with custom Simulink® libraries, referenced models and subsystems, and models, some with hydraulic blocks and some without.

Before converting the files, make sure that topFolder and all its subfolders are on the MATLAB path:

addpath(genpath('topFolder'))

Convert all the files in topFolder and its subfolders:

convertedFiles = hydraulicToIsothermalLiquid('topFolder')

convertedFiles =

  5×1 cell array

    {'model_converted'             }
    {'custom_Library1_converted'   }
    {'custom_Library2_converted'   }
    {'referenceModel_converted'    }
    {'referenceSubsystem_converted'}

The conversion tool forms the new model name by appending _converted to the name of the original model and saves each converted model in the same folder as the original one.

Note that the tool did not generate a _converted file for modelWithoutHydraulicBlocks and did not return its name in the convertedFiles cell array, because this model does not contain hydraulic blocks.

The tool also generates an HTML report, named HtoIL_report.html, and saves it in topFolder. The report lists, for each converted file, any issues encountered during the conversion process.

Review the HTML report and manually fix the remaining issues.

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.

When you convert all files in a folder and its subfolders, the conversion tool updates all the library links, model references, and subsystem references in these files to point to the _converted versions of these files. Once satisfied that the converted systems behave as expected, you can use the hydraulicToIsothermalLiquidPostProcess function to restore the original file names: 

finalFiles = hydraulicToIsothermalLiquidPostProcess('topFolder')

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.

Input Arguments

collapse all

The name of the block diagram system to convert, specified as a character vector, string scalar, or a handle. oldfile can be a model, subsystem, or library. It must be either on the MATLAB path or loaded prior to using the conversion tool. File name can include absolute or relative path name. For more information, see Specify File Names.

Example: 'HydraulicActuator'

Example: 'C:\Work\HydraulicActuator.slx'

Example: 'subfolder\HydraulicActuator'

Location where the tool saves the converted block diagram system and the report, specified as an absolute or relative path name.

This argument is optional. If you omit the newpath argument, the tool saves the converted system and report in your current working folder.

Example: 'C:\Work'

List of the block diagram systems to convert, specified as a one-dimensional cell array of file names, with each file name specified as a character vector or string scalar. The one-dimensional cell array can be horizontal or vertical. File names can include absolute or relative path names. Each of these files can be a model, subsystem, or library, and must be either on the MATLAB path or loaded prior to using the conversion tool. When you convert a list of files, the conversion tool preserves the links between the converted files in the list. The tool saves each converted file in the same folder as the original file, generates a common conversion report, names it HtoIL_report, and saves it at the location of the first file listed in oldfiles.

Example: {'HydraulicActuatorLibrary' 'PumpLibrary'}

Example: {'PumpLibrary';'C:\Work\MyPump.slx'}

Path name of the top folder containing block diagram systems to convert, specified as an absolute or relative path name. The top folder must be on the MATLAB path. The top folder can contain subfolders that also contain block diagram systems. For these systems to be converted, the subfolders must also be on the MATLAB path. The tool preserves the links between the converted files, saves each converted file in the same folder as the original file, names the conversion report HtoIL_report and saves it in toppath folder.

Example: 'C:\Work\MyLibraries'

List of the customized hydraulic blocks to replace, specified as a one-dimensional cell array of file names, with each file name specified as a character vector or string scalar.

List of the customized isothermal liquid blocks to use as replacements for oldcustomfiles, specified as a one-dimensional cell array of file names, with each file name specified as a character vector or string scalar.

Output Arguments

collapse all

Name of the converted model, subsystem, or library, returned as a single-element cell array of character vectors. The character vector is the new file name, without the path or extension. The conversion tool forms the new file name by appending _converted to the name of the original file, oldfile.

Names of the converted models, subsystems, or libraries, returned as a one-dimensional column cell array of file names, without the path or extension. The conversion tool forms each new file name by appending _converted to the name of the original file.

Version History

Introduced in R2020a

expand all

See Also

|

Topics