Skip to content

Update installation.md #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rafapalacios wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update installation.md #325

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e6bdc3b
Update installation.md
rafapalacios Mar 29, 2025
6ca60a3
Merge branch 'main' into rafapalacios-patch-4
ben-l-p May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 55 additions & 49 deletions docs/source/content/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# SHARPy v2.3 Installation Guide
__Last revision 10 June 2024__
# SHARPy v2.4 Installation Guide
__Last revision 29 March 2025__

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

Expand All @@ -14,7 +14,7 @@ SHARPy is being developed and tested on the following operating systems:
* 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
Windows users can also run it by first installing the Windows Subsystem for Linux (https://learn.microsoft.com/en-us/windows/wsl/install). It may be also convenient to install a XServer such as GWSL, which are available through the Microsoft Store. SHARPy is also available to the vast majority of operating systems that support Docker.

__Required Distributions__

Expand Down Expand Up @@ -44,13 +44,14 @@ 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.

Building SHARPy from source, ensures that you get the latest release or (stable) development build.
SHARPy depends on two external libraries, [xbeam](http://github.com/imperialcollegelondon/xbeam) and
[UVLM](http://github.com/imperialcollegelondon/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
The installation has three steps, cloning, installation, and testing. Different alternatives are included below.

### Step 1: Set up the folder structure

Clone `sharpy` in your desired location, if you agree with the license in `license.txt`.
```bash
Expand All @@ -60,9 +61,9 @@ The `--recursive` flag will also initialise and update the submodules SHARPy dep
[xbeam](http://github.com/imperialcollegelondon/xbeam) and [UVLM](http://github.com/imperialcollegelondon/UVLM).


### Quick install (Standalone)
### Step 2 (quick install version): Standalone installation

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](#setting-up-the-python-environment-anaconda), or make a custom installation with a develop build or modified compilation settings [HERE](#custom-installation). The quick install is geared towards getting the release build of SHARPy running as quickly and simply as possible.
The simplest and fastest way to install SHARPy is as a standalone package, without the use of a package manager. If you just want to run the code, that's the recommended approach. The quick install is geared towards getting the release build of SHARPy running as quickly and simply as possible. This mode of installation however will download several packages into your default python environment. To install SHARPy using the Anaconda package manager, please use the following tutorial [HERE](#setting-up-the-python-environment-anaconda), or make a custom installation with a develop build or modified compilation settings [HERE](#custom-installation).

1. Check that your Python version is 3.10 or higher. Other versions may be incompatible with the required modules.
```bash
Expand All @@ -89,11 +90,15 @@ SHARPy can be installed as a standalone package, without the use of a package ma

__You are ready to run SHARPy__. Continue reading the [Running SHARPy](#running-sharpy) section.

### Setting up the Python Environment (Anaconda)
### Step 2 (Anaconda version)

SHARPy can use the Anaconda package manager to provide the necessary Python packages.
This is the suggested approach for developers. 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.

It has two substeps, first, setting the environment and then the installation.

#### Setting up the python environment in Anaconda

1. If you still do not have it in your system, install the [Anaconda](https://conda.io/docs/) Python 3 distribution.

2. Check that your Python version is at least 3.10:
Expand Down Expand Up @@ -130,7 +135,7 @@ These are specified in an Anaconda environment that shall be activated prior to
You should now see ```(sharpy)``` on your command line.


### Quick install (Anaconda)
#### 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:
```bash
Expand Down Expand Up @@ -162,7 +167,7 @@ conda activate sharpy

__You are ready to run SHARPy__. Continue reading the [Running SHARPy](#running-sharpy) section.

### Custom installation
### Step 2 (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.
Expand Down Expand Up @@ -224,6 +229,43 @@ to your taste. This is compatible with both standalone and Anaconda installation

8. This concludes the installation! Continue reading the [Running SHARPy](#running-sharpy) section.

### Step 2 (PyPI route): Obtain SHARPy from PyPI (experimental!)
Copy link
Collaborator

@ben-l-p ben-l-p Apr 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to add some of the disclaimers here about packages which need to be installed prior, as well as it being prebuilt @kccwing ?

Copy link
Collaborator

@ben-l-p ben-l-p May 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realise this PR has been sitting for a while... do we want to make any changes about the PyPi side of things @kccwing or are we good to merge?

Copy link
Collaborator

@kccwing kccwing May 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think @wong-hl is working on the matrix build and hence the tvtk -> vtk to make it happen? Sorry I haven't been keeping up - glad to discuss the next steps.

Copy link
Contributor

@wong-hl wong-hl May 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The matrix build will need a bit of work, as the packaging process needs to be restructured such that each new OS and CPU combination is actually saved as a different wheel. They currently end up in the same wheel and overwrite each other.

The tvtk -> vtk is a separate thing. I think @ben-l-p is also working on it??? I've paused working on it because he mentioned he was doing some stuff on that front and the test suite doesn't catch errors

Copy link
Collaborator

@ben-l-p ben-l-p May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we reserve the build matrix and VTK for future PRs, as I have not had much time to look into implementing calls to VTK. In that instance, I believe this should be good to merge

Copy link
Contributor

@wong-hl wong-hl Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The changes here don't affect the CD so assuming that it will use what is on master then it will publish to PyPI when there is a new release

Copy link
Collaborator

@ben-l-p ben-l-p Jan 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah makes sense. There aren't many new features since we did the last release, more just fixes, but we could do a new release soon and then all will be well

Copy link
Collaborator

@kccwing kccwing Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy new year both! I'll get back to properly creating the distributions and deploying them, thanks!

Copy link
Contributor

@wong-hl wong-hl Jan 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy new year Kelvin!! I had a look into creating the distributions yesterday as I wanted to play around with cibuildwheel on a code base that has native code. I managed to get it working, but it thinks that SHARPy is a pure python wheel... So, I dug a little deeper and I found that when building the sdist (source distribution) it was building the native components due to this line in the setup.py where it invokes the run() method to build the native libraries. This meant that the source only distributions and the platform-dependent distributions were identical, thereby making it appear to be a pure python wheel. Thus, the fix for this is to somehow specify in the packaging/build process that there are native components and where they are found.

From a quick dive into the setuptools docs to see how setup.py could be modified and skim of the page on building extension modules, I found that it expects the native code to be a module (e.g. sharpy.uvlm.sover for binary that it will load). So, once I saw that it invokes the shared object directly through ctypes for the ffi, I gave up and called it a day. It could be that there is a simple fix/trick to it, but it wasn't immediately obvious from the documentation.

Edit: I also looked at numpy, scikit-learn and pycontrails to see if I could nick some code from them but had no luck

TL;DR - I think creating platform dependent distributions of SHARPy won't be trivial and would take more than a day (depends on how tangled up the build process is and if there is an LLM that knows how to deal with this situation)

Copy link
Collaborator

@ben-l-p ben-l-p Jan 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that it's worth spending too much time on this - the pip install from a git clone is not that troublesome. The only actual need for this is for when I go to Airbus, but I can just repeat the way that Kelvin got it working, even if it isn't the most elegant. If others are happy with this, it might just be a good idea to remove mention of the PyPi route from the docs?


You can obtain a built version of SHARPy, ic-sharpy, from PyPI [here](https://pypi.org/project/ic-sharpy/).

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`.

### Step 3: Running SHARPy

SHARPy uses unittests to verify the integrity of the code.

These tests can be run from the `./sharpy` directory.
```bash
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](http://www.github.com/imperialcollegelondon/sharpy/issues) 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

-
## Using SHARPy from a Docker container

> **Tip** To install the Python environment, miniconda needs approximatelly 16GB of
Expand Down Expand Up @@ -303,45 +345,9 @@ python -m unittest

**Enjoy!**

## Obtain SHARPy from PyPI (experimental!)

You can obtain a built version of SHARPy, ic-sharpy, from PyPI [here](https://pypi.org/project/ic-sharpy/).

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.
```bash
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](http://www.github.com/imperialcollegelondon/sharpy/issues) 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
## The SHARPy Case Structure and input files

__Setting up a SHARPy case__

Expand Down
Loading