2.1. Getting started with butterfly in grasshopper - ladybug-tools/butterfly GitHub Wiki

---

Butterfly is python library to create and execute OpenFOAM cases. This page discusses how you can use butterfly from the Butterfly plugin for Grasshopper3D. We appreciate your comments. Let us know your thoughts on github.

_{Follow Ladybug Tools on twitter or like the page on Facebook to get the latest updates.}

In order to use butterfly you need to install OpenFOAM for Windows separately before installing butterfly. If you already haven't installed OpenFOAM check the installation page for OpenFOAM and come back here once you have OpenFOAM installed.

You can download butterfly for Grasshopper from food4Rhino. Scroll to Downloads and download Butterfly latest release by clicking on Download button.

It will download a zip file. Extract the zip file locally. You should see files and folders below in the installation folder.

Open Rhino and Grasshopper and open the installer.gh file. There is a single component in the file which will copy all the files from the installation folder to assigned locations. The installer removes the current installation of butterfly if you have it already installed.

By default butterfly library will be copied to C:\Users\[username]\AppData\Roaming\McNeel\Rhinoceros\5.0\scripts\butterfly and userobjects will be copied to the userobjects folder C:\Users\[username]\AppData\Roaming\Grasshopper\UserObjects.

Once the download is completed successfully you should see butterfly tab added to Grasshopper.

_{If you don't see the tab or all the components close Grasshopper and run UnloadGrasshopperPlugin command in Rhino. Then run Grasshopper command again.}

A number of sample files are available on GitHub which demonstrate different approaches to use butterfly. Here we cover the two most typical workflows for preparing you model in Butterfly. The process of meshing and running the analysis is the same for both workflows.

First step is to prepare the OpenFOAM case folder. The process is explained for outdoor and indoor analysis separately.

The outdoor analysis workflow lets you create an OpenFOAM case from a wind tunnel. The size of the wind tunnel is calculated based on the heights of the test geometries and windTunnelParameters. You can use windTunnelParameters component to adjust the size if necessary. The boundary conditions for inlet, outlet, sides, top and ground surfaces are set by Butterfly. You can change wind speed and wind direction, add refinement regions and set up grading.

Download the Grasshopper definition for outdoor analysis from this link.

For indoor cases, you need to create the butterfly geometries for each group of geometries with similar boundary condition. You can use one of the default boundaries or create your own boundary. Once you have all butterfly geometries you can put them together as a Case.

Download the Grasshopper file for indoor analysis from this link.

There are two required steps for meshing in butterfly which follows OpenFOAM standard workflow. The first step is blockMesh which is followed by running snappyHexMesh. Before running the meshing components you need to have the OpenFOAM docker container running otherwise you will receive an error. You may need to run the Rhino and OpenFoam container as an administrator.

Use decomposeParDict component to run snappyHexMesh in parallel. Butterfly currently supports scotch and simple modes.

_{Check these discussions for troubleshooting in case you get an error message.}

After running each step of meshing you can read the report from the readMe! output. You can also use loadMesh component to load the mesh into Grasshopper. If you're dealing with a very large case then you are probably better off using ParaView. Loading a heavy mesh to Grasshopper can take a lot of memory.

Use snappyHexMeshDict component to set-up the parameters for snappyHexMesh. The refinement values are already set in the previous step. Once you're happy with the mesh density and quality you can move forward to run the analysis. You can also use checkMesh component to check the mesh quality.

The next step before running the analysis is to use pick the right recipe for your analysis. Currently, Butterfly supports two recipes. Steady Incompressible recipe uses simpleFoam and Heat Transfer recipe uses buoyantBoussinesqSimpleFoam. You can customize turbulenceProperties, fvSchemes, fvSolution, residualControl and relaxationFactors for each recipe. You can also create your own recipe by writing a new class.

For running the analysis you need to create a solution. Solution component has several inputs that let you make the final changes to the case or change them while the analysis is running. Similar to snappyHexMesh you can run the solution in parallel.

SolutionParameters is a collection of parameters that can be modified while the analysis is running. controlDict, probes are default parameters that can be modified using their separate components, however, you can use solutionParameter [with no s] component to update any parameter in Case folders. You can even set the parameter to change during the solution after a certain time-step. Check indoor_airflow example file for an example.

You can run the solution by setting _write and run_ to True. Butterfly supports real-time results visualization which means you can load the results for the latestTime while the analysis is running. Click on the image below to watch the video and see the process in action.

_{In case the image link didn't work click here to watch the video.}

You can also plot the residuals while the solution is running either inside Grasshopper or in Rhino screen using Plot Residuals component.

For cases like running an optimization study set _interval_ input to -1. As a result the component will update the results only once after the analysis is over.

You can also use other tools outside of Grasshopper to visualize the results. The image below shows an example of loading the results in ParaView.

We need your input on almost everything! How do you like the current workflow? How do you think the workflow can be improved? What are your thoughts on default boundary conditions? Do you have a set of boundary conditions that you think we should add to the library? What will be your wish for the next release?

Please open an issue for your comments, suggestions and bug reports so other users can also add their inputs. We will get back to you as soon as we can.

Butterfly also has a Python API which lets you to create your own components or modify the butterfly case with typing a couple of lines. Here is the API documentation. You can double click on any of the components to see an example! I will try to provide more examples in the near future.