Installation Instructions

FLOWUnsteady is developed in the Julia programming language, which is a modern, high-level, dynamic programming language for high-performance computing. For visualization and postprocessing, FLOWUnsteady uses ParaView, which is an open-source software for scientific and HPC visualization.

The following instructions walk you through how to install Julia, ParaView, and FLOWUnsteady.

Windows Users

On Windows please follow these instructions first to set up Windows Subsystem for Linux.

Julia

  • Download and install Julia: julialang.org (currently we are supporting up to Julia v1.10, so we recommend using v1.10.2 or v1.6.7 LTS )
  • Add Julia to user-level bin folder
    sudo ln -s /[user-specific-path/Julia-1.x.x]/bin/julia /usr/local/bin/julia
    Replace /[user-specific-path/Julia-1.x.x]/ with the path where Julia got installed. For instance, in MacOS the full path looks like this: /Applications/Julia-1.10.app/Contents/Resources/julia/bin/julia

If you were successfull, typing the following in the terminal will launch the Julia REPL:

julia

ParaView

  • Download and install ParaView: paraview.org
  • Add ParaView to user-level bin folder
    sudo ln -s /[user-specific-path/ParaView-5.x.x]/paraview /usr/local/bin/paraview
    Replace /[user-specific-path/ParaView-5.x.x]/ with the path where ParaView got installed. For instance, in MacOS the full path looks like this: /Applications/ParaView-5.12.0.app/Contents/MacOS/paraview

If you were successfull, typing the following in the terminal will launch the ParaView:

paraview

To test that ParaView is correctly installed, run one of the examples of the GeometricTools package as follows (copy/paste this in the Julia REPL):

# Install GeometricTools
import Pkg; Pkg.add("GeometricTools")

import GeometricTools as gt

# Load example
examplepath = joinpath(dirname(pathof(gt)), "..", "examples", "example_simple.jl")
include(examplepath)

# Run example: it will pull up paraview with a good-looking cube
simple_box2()

ParaView will then pull up with a rendering of a cube (click the Apply button under Properties to make it visible).

Pic here

(Optional) OpenVSP

FLOWUnsteady can import geometry created in OpenVSP using VSPGeom.jl. We recommend installing OpenVSP in your system, then adding VSPGeom.jl to Julia:

] add VSPGeom

PyCall

One of the dependencies (AirfoilPrep.jl) is a wrapper of Python code that is written in Python v3.8+. For this reason, make sure that your Python version linked to PyCall is 3.8 or higher. You can do that as follows:

# Install PyCall
import Pkg; Pkg.add("PyCall")

# Point environment to your Python 3.8 (or higher)
ENV["PYTHON"] = "path/to/your/python3"

# Rebuild PyCall
Pkg.build("PyCall")

Then close and reopen the Julia REPL, and run:

import PyCall
PyCall.pyversion

which should reveal your Python version:

v"3.8"

Since PyCall now relies on a custom install of Python3, make sure that:

  • matplotlib, mpmath, and scipy are installed in that Python,
    pip3 install matplotlib mpmath scipy --user
  • For optimal experience, verify that matplotlib uses the Qt5Agg backend. Useful instructions can be found here and here.

If you run into errors with PyPlot while running FLOWUnsteady, they are likely related to one of those two items.

FLOWVPM

FLOWVPM uses a fast multipole code called ExaFMM that accelerates the computation of particle interactions. ExaFMM is written in C++ and we have developed a Julia wrapper for it: FLOWExaFMM.

Before installing FLOWVPM, first you will have to install FLOWExaFMM and compile ExaFMM, as follows.

  • Make sure you have CMake, GCC, and OpenMP. On Linux, type to following to install them

    sudo apt-get update
    sudo apt-get install cmake g++ mpich
  • [Julia REPL] Install CxxWrap:

    import Pkg
    Pkg.add(name="CxxWrap", version="0.15.0")
  • [Terminal] Clone FLOWExaFMM:

    git clone https://github.com/byuflowlab/FLOWExaFMM path/to/FLOWExaFMM

    (replace path/to/FLOWExaFMM with your preferred path in your local)

  • Compile ExaFMM running the script build.sh:
    cd path/to/FLOWExaFMM
    sh build.sh
    or in MacOS:
    cd path/to/FLOWExaFMM
    sh build_macos.sh
    This should have generated the file fmm.so (or fmm.dylib in MacOS) under src/, which is a binary library containing ExaFMM.

Now that ExaFMM is compiled, you can add FLOWExaFMM to your Julia environment as a development package pointing directly to where you compiled the package and add FLOWVPM:

  • Add FLOWExaFMM:
    # In the Julia REPL
    ] develop path/to/FLOWExaFMM
  • [Optional] Test FLOWExaFMM:
    ] test FLOWExaFMM
    If ExaFMM was correctly compiled, this will return a heart-warming "Hello world!"
  • Add FLOWVPM:
    ] add https://github.com/byuflowlab/FLOWVPM.jl
  • [Optional] Test FLOWVPM:
    ] test FLOWVPM

If you run into any issues, please try the following:

  • Test that you can correctly compile C++ code wrapped for Julia following these instructions: LINK
  • Mac users, take a look at this thread: LINK
  • Instructions for BYU Fulton supercomputer: LINK

If issues persist, please check the resolved issues in the FLOWExaFMM repo, the discussion forum in the FLOWUnsteady repo, and feel free to open a new issue or discussion for help.

Other Packages

Run the following commands in the Julia REPL to add some dependencies that are not in the official Julia registry:

import Pkg

url = "https://github.com/byuflowlab/"

packages = [ ("AirfoilPrep.jl", "v2.1.2"), ("FLOWVLM", "v2.1.2"),
             ("FLOWNoise", "v2.3.3"),      ("BPM.jl", "v2.0.1")  ]

Pkg.add([ Pkg.PackageSpec(; url=url*name, rev=v) for (name, v) in packages ])
Troubleshooting

Some things you might need to look out for:

  • (MacOS users) Make sure your Homebrew (in Julia) is up to date. You may need to run the following in order to update your Homebrew: using Homebrew; Homebrew.brew(`update-reset`)
  • Make sure that things are in place in your Julia settings. Having things like Conda, HDF5, etc. on your machine doesn't necessarily mean that the Julia implementation has them as well.

Add FLOWUnsteady

You are now ready to install the FLOWUnsteady package. Type this in the Julia REPL:

] add https://github.com/byuflowlab/FLOWUnsteady

Test FLOWUnsteady

In order to test that FLOWUnsteady and all dependencies were successfully installed, try running some of the examples under FLOWUnsteady/examples/.

For instance, you can run the Simple Wing example as follows:

import FLOWUnsteady as uns

include(joinpath(uns.examples_path, "wing", "wing.jl"))

or you can run the Tethered Wing example:

import FLOWUnsteady as uns

include(joinpath(uns.examples_path, "tetheredwing.jl"))

This will pull up Paraview visualizing the simulation. Kick off your shoes, sit back, and enjoy the simulation that you have just run.



Vid here








2D View

When opening a simulation with a flat surface (like wing.jl), ParaView automatically activates its 2D view mode. Disable the 2D view by clicking these two buttons: pic

CPU Parallelization

If any of the examples is taking longer than 10 to 20 minutes to run, it is possible that ExaFMM was compiled without OpenMP, thus running in only one core as opposed to parallelizing the computation across all your CPU cores.

To confirm that ExaFMM is successfully parallelized, pull up whatever CPU monitor is available in your operative system and confirm that Julia is using all the cores as the simulation is running. For instance, the Resources tab of the Task Manager in Windows should look like this: pic and htop in the terminal (Linux and MacOS) should look like this: pic