Running simulations — BuildingsPy documentation

# Running simulations

This module contains the class `buildingspy.simulate.OpenModelica`, `buildingspy.simulate.Optimica` and `buildingspy.simulate.Dymola` that can be used to automate simulations using OpenModelica, Optimica and Dymola, respectively.

Their API is identical where possible, but each class may have methods that are only applicable for one of the simulators. For example, the method `buildingspy.simulate.Optimica.Simulator.generateHtmlDiagnostics()` is only available for Optimica.

## Dymola

Class that translates and simulates a Modelica model with Dymola.

This class uses the executable `dmc`, which is the Dymola version that does not require a graphical user interface to translate or simulate a model. dmc was introduced in Dymola 2025x. If `dmc` is not found on the system path, or if a simulation with a user interface is requested, then the `dymola` rather than the `dmc` executable is used.

For a similar class that uses OPTIMICA, see `buildingspy.simulate.Optimica()`.

class buildingspy.simulate.Dymola.Simulator(modelName, outputDirectory='.', packagePath=None)

  Bases: `buildingspy.simulate.base_simulator._BaseSimulator`

  Class to simulate a Modelica model.

  Parameters

    - modelName – The name of the Modelica model.

    - outputDirectory – An optional output directory.

    - packagePath – An optional path where the Modelica `package.mo` file is located.

  If the parameter `outputDirectory` is specified, then the output files and log files will be moved to this directory when the simulation is completed. Outputs from the python functions will be written to `outputDirectory/BuildingsPy.log`.

  If the parameter `packagePath` is specified, then this directory and all its subdirectories will be copied to a temporary directory when running the simulations.

  addModelModifier(modelModifier)

    Adds a model modifier.

    Parameters

      modelModifier – A model modifier.

    Usage: Type

          >>> from buildingspy.simulate.Dymola import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addModelModifier('redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir')

    This method adds a model modifier. The modifier is added to the list of model parameters. For example, the above statement would yield the command `simulateModel(myPackage.myModel(redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir), startTime=...`

  addParameters(dictionary)

    Adds parameter declarations to the simulator.

    Parameters

      dictionary – A dictionary with the parameter values

    Usage: Type

          >>> from buildingspy.simulate.Dymola import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.addParameters({'PID.t': 10.0})

    This will add the three parameters `PID.k`, `valve.m_flow_nominal` and `PID.t` to the list of model parameters.

    For parameters that are arrays, use a syntax such as

          >>> from buildingspy.simulate.Dymola import Simulator
          >>> s = Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'const1.k' : [2, 3]})
          >>> s.addParameters({'const2.k' : [[1.1, 1.2], [2.1, 2.2], [3.1, 3.2]]})

    Do not use curly brackets for the values of parameters, such as `s.addParameters({'const1.k' : {2, 3}})` as Python converts this entry to `{'const1.k': set([2, 3])}`.

  addPostProcessingStatement(command)

    Adds a post-processing statement to the simulation script.

    Parameters

      statement – A script statement.

    This will execute `command` after the simulation, and before the log file is written.

  addPreProcessingStatement(command)

    Adds a pre-processing statement to the simulation script.

    Parameters

      command – A script statement.

    Usage: Type

          >>> from buildingspy.simulate.Dymola import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addPreProcessingStatement("Advanced.StoreProtectedVariables:= true;")
          >>> s.addPreProcessingStatement("Advanced.GenerateTimers = true;")

    This will execute the two statements after the `openModel` and before the `simulateModel` statement.

  deleteOutputFiles()

    Deletes the output files of the simulator.

  exitSimulator(exitAfterSimulation=True)

    This function allows avoiding that the simulator terminates.

    Parameters

      exit – Set to `False` to avoid the simulator from terminating after the simulation.

    This function is useful during debugging, as it allows to keep the simulator open after the simulation in order to inspect results or log messages.

  getOutputDirectory()

    Returns the name of the output directory.

    Returns

      The name of the output directory.

  getPackagePath()

    Returns the path of the directory containing the Modelica package.

    Returns

      The path of the Modelica package directory.

  getParameters()

    Returns a list of parameters as (key, value)-tuples.

    Returns

      A list of parameters as (key, value)-tuples.

    Usage: Type

          >>> from buildingspy.simulate.Dymola import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.getParameters()
          [('PID.k', 1.0), ('valve.m_flow_nominal', 0.1)]

  getSimulatorSettings()

    Returns a list of settings for the parameter as (key, value)-tuples.

    Returns

      A list of parameters (key, value) pairs, as 2-tuples.

    This method is deprecated. Use `getParameters()` instead.

  setNumberOfIntervals(n=500)

    Sets the number of output intervals.

    Parameters

      n – The number of output intervals.

    The default is unspecified, which defaults to 500.

  setOutputDirectory(outputDirectory)

    Sets the name of the output directory.

    Parameters

      outputDirectory – The name of the output directory.

    Returns

      The name of the output directory.

  setPackagePath(packagePath)

    Set the path specified by `packagePath`.

    Parameters

      packagePath – The path where the Modelica `package.mo` file is located.

    It checks whether the file `package.mo` exists in the directory `packagePath`, and then sets the package path. Otherwise, a `ValueError` is raised.

  setResultFile(resultFile)

    Sets the name of the result file (without extension).

    Parameters

      resultFile – The name of the result file (without extension).

  setSolver(solver)

    Sets the solver.

    Parameters

      solver – The name of the solver.

    The default solver is radau.

  setStartTime(t0)

    Sets the start time.

    Parameters

      t0 – The start time of the simulation in seconds.

    The default start time is 0.

  setStopTime(t1)

    Sets the start time.

    Parameters

      t1 – The stop time of the simulation in seconds.

    The default stop time is 1.

  setTimeOut(sec)

    Sets the time out in seconds after which the simulation will be killed.

    Parameters

      sec – The time out after which the simulation will be killed.

    The default value is None, which means that the simulation will never be killed. A value of None, 0 or negative will never time out.

  setTolerance(eps)

    Sets the solver tolerance.

    Parameters

      eps – The solver tolerance.

    The default solver tolerance is 1E-6.

  showGUI(show=True)

    Call this function to show the GUI of the simulator.

    By default, the simulator runs without GUI

  showProgressBar(show=True)

    Enables or disables the progress bar.

    Parameters

      show – Set to false to disable the progress bar.

    If this function is not called, then a progress bar will be shown as the simulation runs.

  simulate()

    Simulates the model.

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates and simulates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `dmc` or `dymola` is on the system `PATH` variable. If it is not found, the function raises an exception.

  translate()

    Translates the model.

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `dmc` or `dymola` is on the system `PATH` variable. If it is not found, the function raises an exception.

## OpenModelica

Class that translates and simulates a Modelica model with OpenModelica.

For a similar class that uses Dymola, see `buildingspy.simulate.Dymola()`.

class buildingspy.simulate.OpenModelica.Simulator(modelName, outputDirectory='.', packagePath=None)

  Bases: `buildingspy.simulate.base_simulator._BaseSimulator`

  Class to simulate a Modelica model with OpenModelica.

  Parameters

    - modelName – The name of the Modelica model.

    - outputDirectory – An optional output directory.

    - packagePath – An optional path where the Modelica `package.mo` file is located.

  If the parameter `outputDirectory` is specified, then the output files and log files will be moved to this directory when the simulation is completed. Outputs from the python functions will be written to `outputDirectory/BuildingsPy.log`.

  If the parameter `packagePath` is specified, then this directory and all its subdirectories will be copied to a temporary directory when running the simulations.

  addModelModifier(modelModifier)

    Adds a model modifier.

    Parameters

      modelModifier – A model modifier.

    Usage: Type

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addModelModifier('redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir')

    This method adds a model modifier. The modifier is added to the list of model parameters. For example, the above statement would yield the command `simulateModel(myPackage.myModel(redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir), startTime=...`

  addParameters(dictionary)

    Adds parameter declarations to the simulator.

    Parameters

      dictionary – A dictionary with the parameter values

    Usage: Type

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.addParameters({'PID.t': 10.0})

    This will add the three parameters `PID.k`, `valve.m_flow_nominal` and `PID.t` to the list of model parameters.

    For parameters that are arrays, use a syntax such as

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s = Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'const1.k' : [2, 3]})
          >>> s.addParameters({'const2.k' : [[1.1, 1.2], [2.1, 2.2], [3.1, 3.2]]})

    Do not use curly brackets for the values of parameters, such as `s.addParameters({'const1.k' : {2, 3}})` as Python converts this entry to `{'const1.k': set([2, 3])}`.

  deleteOutputFiles()

    Deletes the output files of the simulator.

  getOutputDirectory()

    Returns the name of the output directory.

    Returns

      The name of the output directory.

  getPackagePath()

    Returns the path of the directory containing the Modelica package.

    Returns

      The path of the Modelica package directory.

  getParameters()

    Returns a list of parameters as (key, value)-tuples.

    Returns

      A list of parameters as (key, value)-tuples.

    Usage: Type

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.getParameters()
          [('PID.k', 1.0), ('valve.m_flow_nominal', 0.1)]

  setNumberOfIntervals(n=500)

    Sets the number of output intervals.

    Parameters

      n – The number of output intervals.

    The default is unspecified, which defaults to 500.

  setOutputDirectory(outputDirectory)

    Sets the name of the output directory.

    Parameters

      outputDirectory – The name of the output directory.

    Returns

      The name of the output directory.

  setPackagePath(packagePath)

    Set the path specified by `packagePath`.

    Parameters

      packagePath – The path where the Modelica `package.mo` file is located.

    It checks whether the file `package.mo` exists in the directory `packagePath`, and then sets the package path. Otherwise, a `ValueError` is raised.

  setResultFile(resultFile)

    Sets the name of the result file (without extension).

    Parameters

      resultFile – The name of the result file (without extension).

  setSolver(solver)

    Sets the solver.

    Parameters

      solver – The name of the solver.

    The default solver is dassl.

  setStartTime(t0)

    Sets the start time.

    Parameters

      t0 – The start time of the simulation in seconds.

    The default start time is 0.

  setStopTime(t1)

    Sets the start time.

    Parameters

      t1 – The stop time of the simulation in seconds.

    The default stop time is 1.

  setTimeOut(sec)

    Sets the time out in seconds after which the simulation will be killed.

    Parameters

      sec – The time out after which the simulation will be killed.

    The default value is None, which means that the simulation will never be killed. A value of None, 0 or negative will never time out.

  setTolerance(eps)

    Sets the solver tolerance.

    Parameters

      eps – The solver tolerance.

    The default solver tolerance is 1E-6.

  simulate()

    Translates and simulates the model.

    Usage: Type

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s=Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.simulate()

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates and simulates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `omc` is on the system `PATH` variable. If it is not found, the function raises an exception.

  translate()

    Translates the model to generate a Functional Mockup Unit.

    Usage: Type

          >>> from buildingspy.simulate.OpenModelica import Simulator
          >>> s=Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.translate()

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `omc` is on the system `PATH` variable. If it is not found, the function raises an exception.

    Modelica libraries are searched based on the environment variable `MODELICAPATH`, which is appended to the path where OpenModelica installs its Modelica libraries, as received from the OpenModelica function getModelicaPath(). This path can be overridden by setting the environment variable `OPENMODELICALIBRARY`, see the OpenModelica scripting documentation.

## Optimica

Class that translates and simulates a Modelica model with OPTIMICA.

For a similar class that uses Dymola, see `buildingspy.simulate.Dymola()`.

class buildingspy.simulate.Optimica.Simulator(modelName, outputDirectory='.', packagePath=None)

  Bases: `buildingspy.simulate.base_simulator._BaseSimulator`

  Class to simulate a Modelica model with OPTIMICA.

  Parameters

    - modelName – The name of the Modelica model.

    - outputDirectory – An optional output directory.

    - packagePath – An optional path where the Modelica `package.mo` file is located.

  If the parameter `outputDirectory` is specified, then the output files and log files will be moved to this directory when the simulation is completed. Outputs from the python functions will be written to `outputDirectory/BuildingsPy.log`.

  If the parameter `packagePath` is specified, then this directory and all its subdirectories will be copied to a temporary directory when running the simulations.

  addModelModifier(modelModifier)

    Adds a model modifier.

    Parameters

      modelModifier – A model modifier.

    Usage: Type

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addModelModifier('redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir')

    This method adds a model modifier. The modifier is added to the list of model parameters. For example, the above statement would yield the command `simulateModel(myPackage.myModel(redeclare package MediumA = Buildings.Media.IdealGases.SimpleAir), startTime=...`

  addParameters(dictionary)

    Adds parameter declarations to the simulator.

    Parameters

      dictionary – A dictionary with the parameter values

    Usage: Type

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.addParameters({'PID.t': 10.0})

    This will add the three parameters `PID.k`, `valve.m_flow_nominal` and `PID.t` to the list of model parameters.

    For parameters that are arrays, use a syntax such as

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s = Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'const1.k' : [2, 3]})
          >>> s.addParameters({'const2.k' : [[1.1, 1.2], [2.1, 2.2], [3.1, 3.2]]})

    Do not use curly brackets for the values of parameters, such as `s.addParameters({'const1.k' : {2, 3}})` as Python converts this entry to `{'const1.k': set([2, 3])}`.

  deleteOutputFiles()

    Deletes the output files of the simulator.

  generateHtmlDiagnostics(generate=True)

    If set to true, html diagnostics will be generated.

    The html diagnostics will be generated in a directory whose name is equal to the model name, with `.` replaced by `_`, and the string `_html_diagnostics` appended.

    Note

    For large models, this can generate huge files and increase translation time.

  getOutputDirectory()

    Returns the name of the output directory.

    Returns

      The name of the output directory.

  getPackagePath()

    Returns the path of the directory containing the Modelica package.

    Returns

      The path of the Modelica package directory.

  getParameters()

    Returns a list of parameters as (key, value)-tuples.

    Returns

      A list of parameters as (key, value)-tuples.

    Usage: Type

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.addParameters({'PID.k': 1.0, 'valve.m_flow_nominal' : 0.1})
          >>> s.getParameters()
          [('PID.k', 1.0), ('valve.m_flow_nominal', 0.1)]

  setNumberOfIntervals(n=500)

    Sets the number of output intervals.

    Parameters

      n – The number of output intervals.

    The default is unspecified, which defaults to 500.

  setOutputDirectory(outputDirectory)

    Sets the name of the output directory.

    Parameters

      outputDirectory – The name of the output directory.

    Returns

      The name of the output directory.

  setPackagePath(packagePath)

    Set the path specified by `packagePath`.

    Parameters

      packagePath – The path where the Modelica `package.mo` file is located.

    It checks whether the file `package.mo` exists in the directory `packagePath`, and then sets the package path. Otherwise, a `ValueError` is raised.

  setResultFile(resultFile)

    Sets the name of the result file (without extension).

    Parameters

      resultFile – The name of the result file (without extension).

  setResultFilter(filter)

    Specifies a list of variables that should be stored in the result file.

    Parameters

      filter – A list of variables that should be stored in the result file.

    Usage: To list only the variables of the instance myStep.source, type

        >>> from buildingspy.simulate.Optimica import Simulator
        >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
        >>> s.setResultFilter(["myStep.source.*"])

    To list all variables whose name ends in `y`, type

        >>> from buildingspy.simulate.Optimica import Simulator
        >>> s=Simulator("myPackage.myModel", packagePath="buildingspy/tests/MyModelicaLibrary")
        >>> s.setResultFilter(["*y"])

  setSolver(solver)

    Sets the solver.

    Parameters

      solver – The name of the solver.

    The default solver is CVode.

  setStartTime(t0)

    Sets the start time.

    Parameters

      t0 – The start time of the simulation in seconds.

    The default start time is 0.

  setStopTime(t1)

    Sets the start time.

    Parameters

      t1 – The stop time of the simulation in seconds.

    The default stop time is 1.

  setTimeOut(sec)

    Sets the time out in seconds after which the simulation will be killed.

    Parameters

      sec – The time out after which the simulation will be killed.

    The default value is None, which means that the simulation will never be killed. A value of None, 0 or negative will never time out.

  setTolerance(eps)

    Sets the solver tolerance.

    Parameters

      eps – The solver tolerance.

    The default solver tolerance is 1E-6.

  simulate()

    Translates and simulates the model.

    Usage: Type

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s=Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.simulate()

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates and simulates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `jm_ipython.sh` is on the system `PATH` variable. If it is not found, the function raises an exception.

  translate()

    Translates the model to generate a Functional Mockup Unit.

    Usage: Type

          >>> from buildingspy.simulate.Optimica import Simulator
          >>> s=Simulator("MyModelicaLibrary.Examples.Constants", packagePath="buildingspy/tests/MyModelicaLibrary")
          >>> s.translate()

    This method

      1. Deletes output files

      2. Writes a script to simulate the model.

      3. Starts the Modelica simulation environment.

      4. Translates the model.

      5. Closes the Modelica simulation environment.

    This method requires that the directory that contains the executable `jm_ipython.sh` is on the system `PATH` variable. If it is not found, the function raises an exception.