How to Migrate EnergyPlus Python Plugins

This page provides guidance on steps that may need to be taken to make existing EnergyPlus Python Plugins work when uploaded to Alfalfa. For more information about creating EnergyPlus Python Plugins see the EnergyPlus Documentation.

Python Versions

When beginning to migrate an EnergyPlus Python Plugin for use with Alfalfa it is important to check that the version of python which Alfalfa uses is the same as what you are using locally to develop your plugin. To find the version used by Alfalfa you can consult the Alflalfa Dependency Version Matrix. Alfalfa uses the same version of Python which is packaged with so in most cases checking that the EnergyPlus versions are the same is enough. Note that multiple versions of EnergyPlus use the same version of Alfalfa.

Dependencies

If you are using packages outside of the Python standard library you will need to tell Alfalfa to install those packages with your model. This is done by including a Python requirements file named requirements.txt somewhere in your model. Usually I put this file within the measure so that if I copy that measure to other workflows it maintains its dependency list. You can include multiple requirements.txt files in different places in your model and all will be installed. Below is an example of a basic requirements.txt file.

sklearn
pysindy
CoolProp

PythonPlugin:SearchPaths

Currently Alfalfa needs an existing PythonPlugin:SearchPaths IddObject in order to install dependencies for your model. You likely already have this object in your model if you need dependencies to be installed with your plugin. Below is a snippet example from an EnergyPlus measure which creates the PythonPlugin:SearchPaths object.

    workspace.getObjectsByType('PythonPlugin_SearchPaths'.to_IddObjectType).each do |o|
      if (RUBY_PLATFORM =~ /linux/) != nil
        o.setString(4,'/usr/local/lib/python3.8/dist-packages')
        o.setString(5,'/usr/local/EnergyPlus-23-1-0')
      elsif (RUBY_PLATFORM =~ /darwin/) != nil
        o.setString(4,'/usr/local/lib/python3.8/site-packages')
        o.setString(5,'/Applications/EnergyPlus-23-1-0')
      elsif (RUBY_PLATFORM =~ /cygwin|mswin|mingw|bccwin|wince|emx/) != nil
        o.setString(4,"#{ENV['USERPROFILE']}/AppData/Local/Programs/Python/Python38/Lib/site-packages")
        o.setString(5,'C:/EnergyPlusV23-1-0')
      end
      runner.workflow.absoluteFilePaths.each {|p| o.setString(6,p.to_s) if p.to_s.include?('python')}
    end