Running Script Files and Functions with Batch

You can execute script files and functions of Dymola behavior libraries with the batch utility. This is useful to automate this operation, or to perform it on a remote computer.

For more about running batches, see 3DEXPERIENCE Native Apps: Batches and Plug-in Methods.

Note: It is also possible to run script files and functions, together with behavior experience simulations, with Batch, see Behavior Experience User´s Guide: Running a Simulation: Running a Behavior Experience with Batch.

This task shows you how to run a script file and a function of a Dymola behavior library with batch. The first section is about preparing the library and the included script file and function.

See Also
About Scripting

Preparation: Create a Dymola Behavior Library Containing a Script File and a Function

In this subtask, you create a Dymola behavior library with a simple script file and a simple function to be able to exemplify scripting with batch.

Note: The script file and function are not very realistic, they are the minimum to be able to exemplify scripting with batch.

  1. Create a Dymola behavior library and name it MyLib.

    For information on how to create a Dymola behavior library, see Creating a Modelica Library or Dymola Behavior Library.

  2. In the library, create a model and name it MyModel.

    For information on how to create a model, see Create a New Class or Extend from an Existing Class Using the New Class Command.

  3. Create a script the following way:

    The script, when ready, looks like: 

    openModelFile("Modelica");
simulateModel("Modelica.Mechanics.Rotational.Examples.CoupledClutches",0,1.5);
plot({"J1.w"});
ExportPlotAsImage("E:/temp/plot.png");

    The script opens the Modelica Standard Library, simulate the model Coupled Clutches, plot a signal, and export the plot image to a folder on the computer.

    Note: The first line might seem redundant since the Modelica Standard Library is often by default opened by preferences or specified in uses-annotations. However, this is a precaution since the script might be used on a remote computer that does not have this preference activated and the uses-annotations might not be present.

    1. Open the script editor, and create the script in the editor.

      For opening and editing a script in the script editor, see Creating a New Script and Editing a Script.

    2. Save the script as a resource to MyModel, with the name MyScript.

      To save the script as a resource from the script editor, see Save a New Script to the Resources.

      Note: It is possible to save the script as a file on the computer, and to later call that script from the batch by the file path. However, this is not recommended since it does not work on remote computers.

  4. Create a function in the library the following way:

    The function, when ready, looks like: 

    function MyFunction
  input String ModelToSimulate;
  input String SignalToPlot;
  input String PlotExportPath;
algorithm 
  openModelFile("Modelica");
  simulateModel(ModelToSimulate, 0, 1.5);
  plot({SignalToPlot});
  ExportPlotAsImage(PlotExportPath);
end MyFunction;

    The function does the following:

    1. It opens the Modelica Standard Library.
    2. It simulates a model from the Modelica Standard Library. The model must be specified in the call.
    3. It plots a signal specified in the call.
    4. It exports the plot as an image to a location specified in the call.
    Notes:
    • The first line in algorithm might seem redundant since the Modelica Standard Library is often by default opened by preferences or specified in uses-annotations. However, this is a precaution since the script might be used on a remote computer that does not have this preference activated and the uses-annotations might not be present.
    • If you simulate a model from another library, you must open also that library with the openModelFile function.

    1. Create, in MyLib, a function with the name MyFunction.

      For creating a function, see Create a New Class or Extend from an Existing Class Using the New Class Command

      Note: Be sure to insert the function in MyLib when creating it.

  5. Save the library with Share > Save.

Execute the Script File and the Function with Batch From a Session

You can execute script files and functions of Dymola behavior libraries with the batch utility.

You can start the batch utility from any app during a session.

Before you begin:

Perform the task above to have an example to work with.

  1. From the Tools section of the action bar, click Utility .

    The Batch Monitor is a separate application, this means you might have to supply a password and select options when starting it.

    The Batch Monitor appears to let you select the convenient batch.
  2. Double-click CATSymBatchExecuter.
    The CATSymBatchExecuter dialog box appears to let you select a behavior library.
  3. Click 3DEXPERIENCE Platform Object Search to select a behavior library.
    The 3DEXPERIENCE Platform Object Search dialog box appears.
  4. In the Object Selection tab of the dialog, do the following to perform a simple search for a behavior library by the title:
    1. In the Object box, select, from the list, Behavior Library Reference.
    2. In the Extension box, keep (No Extension).
    3. In the Easy tab, use the Title field to search the title of the library, by entering a text string.

      Tips:
      • You can use the star * as wildcard, typing, for example *My* to search for all libraries containing "My" in the title.
      • You can display a list of previous text strings entered.
      • You can select if you want to use case sensitive search by selecting or clearing Case sensitive.

      In this example, use *My* to be able to find MyLib.

    4. Keep the default selection Add Results.
    5. Click Apply to perform the search.

      Important: You must click Apply to perform the search, you cannot directly click OK.

      The CATSymBatchExecuter dialog box displays your selection.
    6. Click OK to close the search dialog.
    7. Delete all search results except the search result you want to work with.

      In this example, delete all libraries except MyLib.

  5. To select the script file and function to be executed, do the following:
    1. Click the Selected Operation tab.
    2. Enter the name of the Modelica script file and the Modelica function that you want to execute together with the scenario.

      Important:
      • The function must be present in the model from which the scenario was created.
      • It is highly recommended to store the script file as a resource in the library that the above model belongs to, to ensure that the batch works also on a remote computer.

      In this example, specify the following paths and inputs:

      1. In the Modelica script field, enter modelica://MyLib/MyScript.mos
      2. In the Modelica function field, enter: MyLib.MyFunction("Modelica.Electrical.Analog.Examples.CauerLowPassAnalog", "R1.i", "E:/temp/MyPlot2.png")

  6. Optional: Click Save to create an .xml file from the behavior experience batch.

    Important: You need such an .xml file to perform the batch from a prompt command.

  7. Click Run to start the behavior experience batch.
    The CATBatchStarter.exe is launched.

You can check the result in the .htm report.

Note: On your computer, in E:/temp, you have two plot images if the batch for the example succeeded.

From a Prompt Command

You can start the behavior experience batch without entering any app.

Before you begin:

Save your behavior experience in an .xml file.

  1. Open a prompt command.
  2. Type one of the following command lines:
    • CATUTIL -Name CATBatchStarter xml_file
    • catstart -run "CATBatchStarter" -input xml_file -host remote_machine
    • CATBatchStarter -input xml_file
    The CATBatchStarter.exe is launched.

You can check the result in the .htm report.

On a Remote Computer

You can start the behavior experience batch on a remote computer.

  1. Open a prompt command.
  2. Launch a daemon service by entering the following command line:
    • catstart -run "CATBatSrvMonitorExe BB"
  3. Launch the behavior experience batch by entering one of the following command lines:
    • CATUTIL -Name CATBatchStarter xml_file
    • catstart -run "CATBatchStarter" -input xml_file -host remote_machine
    • CATBatchStarter -input xml_file
    The CATBatchStarter.exe is started on the remote computer.

You can check the result in the .htm report.

Check the Result in a .htm File

A .htm report with the name SimulationReport_.htm is generated to let you verify your behavior experience result.

  1. Enter the dedicated folder. By default, this folder is: C:\DOCUME~1\BJZ\LOCALS~1\Temp

    Note: This path can be customized when launching the batch from the Behavior Experience Batch dialog box, in the Report tab.

  2. Open the SimulationReport_.htm file.
    The batch process is described.
  3. In the report, click the minor green OK to access a .htm report with the behavior experience results.

Working with the Process Composer

You can, in the Process Composer app, use the System Experiment Batch utility to execute selected scripts and functions of a Dymola behavior library.

For more information, see Process Composer User´s Guide: Using Adapters: Function Adapters: 3DEXPERIENCE Utility Adapter: Configuring the 3DEXPERIENCE Utility Adapter: Configuring the Execution of a 3DEXPERIENCE Utility: Executing Modelica Functions and Scripts and CATIA System Behavior Simulations.