SHARPy v2.3 Installation Guide

Last revision 10 June 2024

The following step by step tutorial will guide you through the installation process of SHARPy. This is the updated process valid from v2.3.

Requirements

Operating System Requirements

SHARPy is being developed and tested on the following operating systems:

  • CentOS 7 and CentOS 8

  • Ubuntu 22.04 LTS

  • Debian 12

  • MacOS Mojave and Catalina (Intel)

  • MacOS Sonoma (Apple Silicon M2)

Windows users can also run it by first installing the Windows Subsystem for Linux (https://learn.microsoft.com/en-us/windows/wsl/install) and a XServer such as GWSL, which can be installed through the Microsoft Store. SHARPy is also available to the vast majority of operating systems that are supported by Docker

Required Distributions

  • Python 3.10 or higher

  • CMake

  • GCC 6.0 or higher, G++, GFortran (all included in Anaconda)

  • Eigen3, BLAS, MKL/LAPACK (all included in Anaconda)

If the prerequisite packages are not installed and you are not using Anaconda, they can be installed as following on Linux (with a Homebrew equivelent available for Mac installs):

sudo apt install -y cmake g++ gfortran libblas-dev liblapack-dev libeigen3-dev

Recommended Software

You may find the applications below useful, we recommend you use them but cannot provide any direct support.

  • HDFView to read and view .h5 files. HDF5 is the SHARPy input file format.

  • Paraview to visualise SHARPy’s output.

SHARPy can be installed from the source code available on GitHub or you can get it packed in a Docker container. If what you want is to give it a go and run some static or simple dynamic cases (and are familiar with Docker), we recommend the Docker route. If you want to check the code, modify it and compile the libraries with custom flags, build it from source (recommended).

Building SHARPy from source (release or development builds)

SHARPy can be built from source so that you can get the latest release or (stable) development build.

SHARPy depends on two external libraries, xbeam and UVLM. These are included as submodules to SHARPy and therefore once you initialise SHARPy you will also automatically clone the relevant versions of each library.

Set up the folder structure

Clone sharpy in your desired location, if you agree with the license in license.txt.

git clone --recursive http://github.com/ImperialCollegeLondon/sharpy

The --recursive flag will also initialise and update the submodules SHARPy depends on, xbeam and UVLM.

Quick install (Standalone)

SHARPy can be installed as a standalone package, without the use of a package manager. If you wish to install using the Anaconda package manager, please use the following tutorial HERE, or make a custom installation with a develop build or modified compilation settings HERE. The quick install is geared towards getting the release build of SHARPy running as quickly and simply as possible.

  1. Check that your Python version is 3.10 or higher. Other versions may be incompatible with the required modules.

    python --version
    
  2. Move into the cloned repository:

    cd sharpy
    
  3. Install SHARPy. This will install any required Python packages as well as building the xbeam and UVLM libraries, and may take a few minutes.

    pip install --user .
    

    The --user flag is included for systems without root access (often Linux) as the install will fail otherwise. This flag can be removed when a global install is required, and your machine allows it (works on Mac).

    There are options for what to install if required. For instance, to install the basic package with documentation, just do bash pip install --user .[docs]. For the whole lot, bash pip install --user .[all].

  4. You can check the version of SHARPy you are running with:

    sharpy --version
    

You are ready to run SHARPy. Continue reading the Running SHARPy section.

Setting up the Python Environment (Anaconda)

SHARPy can use the Anaconda package manager to provide the necessary Python packages. These are specified in an Anaconda environment that shall be activated prior to compiling the xbeam and UVLM libraries or running any SHARPy cases.

  1. If you still do not have it in your system, install the Anaconda Python 3 distribution.

  2. Check that your Python version is at least 3.10:

    python --version
    
  3. If a specific python version is required, for example 3.10, use:

    conda install python=3.10
    
  4. Create the conda environment that SHARPy will use:

    conda env create -f environment.yml
    

    This should take approximately 5 minutes to complete (Tested on Ubuntu 22.04.1). For installation on Apple Silicon, use environment_arm64.yml; this requires GCC and GFortran to be installed prior.

    Installation using Conda can be memory intensive, and will give the message Collecting package metadata (repodata.json): - Killed if all the available RAM is filled. From testing, 16GB of total system RAM is reliable for Conda install, whereas 8GB may have issues. Three solutions are available:

    • Increase available RAM (if running on a compute cluster etc)

    • Use Mamba, a more efficient drop-in replacement for Conda

    • Create a blank conda environment and install the required packages:

      conda create --name sharpy python=3.10
      conda config –add channels conda-forge
      conda install eigen libopenblas libblas libcblas liblapack libgfortran libgcc libgfortran-ng
      
  5. Activate the sharpy conda environment:

    conda activate sharpy
    

    You should now see (sharpy) on your command line.

Quick install (Anaconda)

The quick install is geared towards getting the release build of SHARPy running as quickly and simply as possible.

  1. Move into the cloned repository:

    cd sharpy
    
  2. Ensure that the SHARPy environment is active in the session. Your terminal prompt line should begin with:

    (sharpy) [usr@host] $
    
  3. Install SHARPy. This will install any required Python packages as well as building the xbeam and UVLM libraries, and may take a few minutes.

    pip install --user .
    

    The --user flag is included for systems without root access (often Linux) as the install will fail otherwise. This flag can be removed when a global install is required, and your machine allows it (works on Mac).

    There are options for what to install if required. For instance, to install the basic package with documentation, just do bash pip install --user .[docs]. For the whole lot, bash pip install --user .[all].

  4. You can check the version of SHARPy you are running with:

    sharpy --version
    

If running SHARPy from Anaconda, you need to load the conda environment. Therefore, before you run any SHARPy case or test, activate the SHARPy conda environment:

conda activate sharpy

You are ready to run SHARPy. Continue reading the Running SHARPy section.

Custom installation

These steps will show you how to compile the xbeam and UVLM libraries such that you can modify the compilation settings to your taste. This is compatible with both standalone and Anaconda installations.

  1. If you want to use SHARPy’s latest release, skip this step. If you would like to use the latest development work, you will need to checkout the develop branch. For more info on how we structure our development and what branches are used for what kind of features have a look at the Contributing page.

    git checkout develop
    git submodule update --recursive
    

    This command will check out the develop branch and set it to track the remote origin. It will also set the submodules (xbeam and UVLM) to the right commit.

  2. If using Anaconda, create the conda environment that SHARPy will use and activate the environment:

    conda env create -f environment.yml
    
    conda activate sharpy
    
  3. Create a directory build that will be used during CMake’s building process and cd into it:

    mkdir build
    cd build
    
  4. Run CMake with custom flags:

    1. Choose your compilers for Fortran FC and C++ CXX, for instance:

      FC=gfortran CXX=g++ cmake ..
      

      If you’d like to use the Intel compilers you can set them using:

      FC=ifort CXX=icpc cmake ..
      
    2. Alternatively, you can build the libraries in debug mode with the following flag for cmake:

      -DCMAKE_BUILD_TYPE=Debug
      
  5. Compile the libraries and parallelise as you prefer.

    make install -j 4
    
  6. Finally, leave the build directory and install SHARPy.

    cd ..
    pip install .
    

    If you want to install it in development mode (the source files will stay where the are so you can modify them), you can make an editable install:

    pip install -e .
    

    You can obtain further information on editable installs here

  7. This concludes the installation! Continue reading the Running SHARPy section.

Using SHARPy from a Docker container

Tip To install the Python environment, miniconda needs approximatelly 16GB of memory. It is recommended to have at least that amount available for the container in which you are building SHARPy.

Docker containers are similar to lightweight virtual machines. The SHARPy container distributed through Docker Hub is a CentOS 8 machine with the libraries compiled with gfortran and g++ and an Anaconda Python distribution.

Make sure your machine has Docker working. The instructions are here: link.

You might want to run a test in your terminal:

docker pull hello-world
docker run hello-world

If this works, you’re good to go!

First, obtain the SHARPy docker container:

docker pull ghcr.io/imperialcollegelondon/sharpy:main

You can obtain other versions as well, check those available in the containers page.

This will donwload a Docker image of SHARPy to your machine, from where you can create and run Docker containers. To create and run a container from the downloaded image use:

docker run --name sharpy -it -p 8080:8080 ghcr.io/imperialcollegelondon/sharpy:main

A few details about the above command, although if in doubt please check the Docker documentation. The --name argument gives a name to the container. Note you can create multiple containers from a single image.

The -it is an important command as it runs the container in interactive mode with a terminal attached. Thus you can use it an navigate it. Otherwise the container will finish as soon as it is created.

The -p 8080:8080 argument connects the container to your machine through port 8080 (it could be any other) which may be useful for some applications. For instance, running SHARPy as hardware-in-the-loop through UDP.

Once you run it, you should see a welcome dialog such as:

>>>> docker run --name sharpy -it -p 8080:8080 ghcr.io/imperialcollegelondon/sharpy:main
SHARPy added to PATH from the directory: /sharpy_dir/bin
=======================================================================
Welcome to the Docker image of SHARPy
SHARPy is located in /sharpy_dir/ and the
environment is already set up!
Copyright Imperial College London. Released under BSD 3-Clause license.
=======================================================================
SHARPy>

You are now good to go.

You can check the version of SHARPy you are running with

sharpy --version

It is important to note that a docker container runs as an independent operating system with no access to your hard drive. If you want to copy your own files, run the container and from another terminal run:

docker cp my_file.txt sharpy:/my_file.txt     # copy from host to container
docker cp sharpy:/my_file.txt my_file.txt     # copy from container to host

The sharpy: part is the --name argument you wrote in the docker run command.

Enjoy!

Testing with Docker

You can run the test suite once inside the container as:

cd sharpy_dir
python -m unittest

Enjoy!

Obtain SHARPy from PyPI (experimental!)

You can obtain a built version of SHARPy, ic-sharpy, from PyPI here.

To install at default directory use

python3 -m pip install ic-sharpy

To install at current directory use

python3 -m pip install --prefix . ic-sharpy

The source code can be found at /lib/python3.10/site-packages/sharpy and the executable at /bin/sharpy.

Running SHARPy

Automated tests

SHARPy uses unittests to verify the integrity of the code.

These tests can be run from the ./sharpy directory.

python -m unittest

The tests will run and you should see a success message. If you don’t… check the following options:

  • Check you are running the latest version. Running the following from the root directory should update to the latest release version:

    • git pull

    • git submodule update --init --recursive

  • If the tests don’t run, make sure you have followed correctly the instructions and that you managed to compile xbeam and UVLM.

  • If some tests fail, i.e. you get a message after the tests run saying that certain tests did not pass, please open an issue with the following information:

    • Operating system

    • Whether you did a Custom/quick install

    • UVLM and xbeam compiler of choice

    • A log of the tests that failed

The SHARPy Case Structure and input files

Setting up a SHARPy case

SHARPy cases are usually structured in the following way:

  1. A generate_case.py file: contains the setup of the problem like geometry, flight conditions etc. This script creates the output files that will then be used by SHARPy, namely:

    • The structural .fem.h5 file.

    • The aerodynamic .aero.h5 file.

    • Simulation information and settings .sharpy file.

    • The dynamic forces file .dyn.h5 (when required).

    • The linear input files .lininput.h5 (when required).

    • The ROM settings file .rom.h5 (when required).

    See the chapter on the case files for a detailed description on the contents of each one. Data is exchanged in binary format by means of .h5 files that make the transmission efficient between the different languages of the required libraries. To view these .h5 files, a viewer like HDF5 is recommended.

  2. The h5 files contain data of the FEM, aerodynamics, dynamic conditions. They are later read by SHARPy.

  3. The .sharpy file contains the settings for SHARPy and is the file that is parsed to SHARPy.

To run a SHARPy case

SHARPy cases are therefore usually ran in the following way:

  1. Create a generate_case.py file following the provided templates.

  2. Run it to produce the .h5 files and the .sharpy files.

    python generate_case.py
    
  3. Run SHARPy (ensure the environment is activated).

    sharpy case.sharpy
    

Output

By default, the output is located in the output folder.

The contents of the folder will typically be a beam and aero folders, which contain the output data that can then be loaded in Paraview. These are the .vtu format files that can be used with Paraview.

Running (and modifiying) a test case

  1. This command generates the required files for running a static, clamped beam case that is used as part of code verification:

    cd ../sharpy
    python ./tests/xbeam/geradin/generate_geradin.py
    

Now you should see a success message, and if you check the ./tests/xbeam/geradin/ folder, you should see two new files:

  • geradin_cardona.sharpy

  • geradin_cardona.fem.h5

Try to open the sharpy file with a plain text editor and have a quick look. The sharpy file is the main settings file. We’ll get deeper into this later.

If you try to open the fem.h5 file, you’ll get an error or something meaningless. This is because the structural data is stored in HDF5 format, which is compressed binary.

  1. Run it (part 1)

    The sharpy call is:

    sharpy <path to solver file>
    
  2. Results (part 1)

    Since this is a test case, there is no output directly to screen.

    We will therefore change this setting first. In the generate_geradin.py file, look for the SHARPy setting write_screen and set it to on. This will output the progress of the execution to the terminal.

    We would also like to create a Paraview file to view the beam deformation. Append the post-processor BeamPlot to the end of the SHARPy setting flow, which is a list. This will run the post-processor and plot the beam in Paraview format with the settings specified in the generate_geradin.py file under config['BeamPlot].

  3. Run (part 2)

    Now that we have made these modifications, run again the generation script:

    python ./tests/xbeam/geradin/generate_geradin.py
    

    Check the solver file geradin.sharpy and look for the settings we just changed. Make sure they read what we wanted.

    You are now ready to run the case again:

    sharpy <path to solver file>
    
  4. Post-processing

    After a successful execution, you should a long display of information in the terminal as the case is being executed.

    The deformed beam will have been written in a .vtu file and will be located in the output/ folder (or where you specified in the settings) which you can open using Paraview.

    In the output directory you will also note a folder named WriteVariablesTime which outputs certain variables as a function of time to a .dat file. In this case, the beam tip position deflection and rotation is written. Check the values of those files and look for the following result:

        Pos_def:
    	      4.403530 0.000000 -2.159692
        Psi_def:
    	      0.000000 0.672006 0.000000
    

    FYI, the correct solution for this test case by Geradin and Cardona is Delta R_3 = -2.159 m and Psi_2 = 0.6720 rad.

Congratulations, you’ve run your first case. You can now check the Examples section for further cases.