From 89a3cea8dd8d08899d069862504b4cd94d858e30 Mon Sep 17 00:00:00 2001 From: Ryan Mast Date: Fri, 6 Mar 2020 16:48:29 -0800 Subject: [PATCH] Add pip to install docs (#1127) * Update the SWIG developer guide on Python * Add HELICS Python interface install instructions using pip --- docs/developer-guide/swig.md | 10 ++++++---- docs/installation/index.md | 11 ++++++++++- docs/installation/package_manager.md | 15 +++++++++++++++ docs/introduction/python.md | 6 ++---- 4 files changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/developer-guide/swig.md b/docs/developer-guide/swig.md index 06adf05b9d..8bd2bb5468 100644 --- a/docs/developer-guide/swig.md +++ b/docs/developer-guide/swig.md @@ -5,13 +5,13 @@ Generating SWIG extension **Python** The easiest way to generate the latest C files for the Python extension is to use CMake itself. -For example, you can run the following on an OSX machine where you have `swig` installed. +For example, you can run the following in a POSIX/Unix environment where you have `swig` installed with Python 3.6. ```bash git clone https://github.com/GMLC-TDC/HELICS cd HELICS -mkdir build-osx -cmake -DBUILD_PYTHON_INTERFACE=ON -DPYTHON_INCLUDE_DIR=$(python3-config --prefix)/include/python3.6m/ -DCMAKE_INSTALL_PREFIX=/Users/$(whoami)/local/helics-develop/ .. && make -j 8 && make install +mkdir build +cmake -DBUILD_PYTHON_INTERFACE=ON -DPYTHON_INCLUDE_DIR=$(python3-config --prefix)/include/python3.6m/ -DCMAKE_INSTALL_PREFIX=$HOME/local/helics-develop/ .. && make -j 8 && make install cd swig/python cp helicsPYTHON_wrap.c ../../../swig/python/helics_wrap.c cp helics.py ../../../swig/python/helics.py @@ -19,6 +19,8 @@ cp helics.py ../../../swig/python/helics.py This method verifies that the C file generated from CMake using SWIG compiles correctly into a Python extension. +For building a Python 2 compatible interface, use BUILD_PYTHON2_INTERFACE instead of BUILD_PYTHON_INTERFACE. + **MATLAB** For the MATLAB extension, you need a special version of SWIG. Get it [here](https://github.com/jaeandersson/swig). @@ -33,7 +35,7 @@ The matlab interface can be built using BUILD_MATLAB_INTERFACE in the cmake bui **Octave** [Octave](https://www.gnu.org/software/octave/) is a free program that works similarly to MATLAB -Building the octave interface requires swig, and currently will work with Octave 4.0 through 4.2. 4.4 is not currently supported by SWIG unless you build from the current master of the swig repo and use that version. The next release of swig will likely support it. It does work on windows, though the actual generation is not fully operational for unknown reasons and will be investigated at some point. A mkhelicsOCTFile.m is generated in the build directory this needs to be executed in octave, then a helics.oct file should be generated, the libHelicsShared.dll needs to be copied along with the libzmq.dll files Once this is done the library can be loaded by calling helics. On linux this build step is done for you. with the BUILD_OCTAVE_INTERFACE. +Building the octave interface requires swig, and currently will work with Octave 4.0 through 4.2. 4.4 is not currently supported by SWIG unless you build from the current master of the swig repo and use that version. The next release of swig will likely support it. It does work on windows, though the actual generation is not fully operational for unknown reasons and will be investigated at some point. A mkhelicsOCTFile.m is generated in the build directory this needs to be executed in octave, then a helics.oct file should be generated, the libHelicsShared.dll needs to be copied along with the libzmq.dll files Once this is done the library can be loaded by calling helics. On linux this build step is done for you with BUILD_OCTAVE_INTERFACE. **C#** A C# interface can be generated using swig and enabling BUILD_CSHARP_INTERFACE in the CMake. The support is partial; it builds and can be run but not all the functions are completely usable and it hasn't been fully tested. diff --git a/docs/installation/index.md b/docs/installation/index.md index f8e7188ad2..4c0b9330bd 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -14,12 +14,21 @@ Get the latest installers from [GitHub Releases](https://github.com/GMLC-TDC/HEL OR -Use conda to install helics: +Use conda to install the HELICS Python interface and apps: ```bash conda install -c gmlc-tdc helics ``` +OR + +Use pip to install the HELICS Python interface and apps: + +```bash +pip install helics +pip install helics-apps +``` + ### Using an installer for your operating system Download pre-compiled libraries from the [releases page](https://github.com/GMLC-TDC/HELICS/releases/latest) and add them to your path. diff --git a/docs/installation/package_manager.md b/docs/installation/package_manager.md index dbc661669a..347f62ce39 100644 --- a/docs/installation/package_manager.md +++ b/docs/installation/package_manager.md @@ -12,3 +12,18 @@ You can then use `conda` to install HELICS. conda install -c gmlc-tdc helics ``` +## Install using pip (Windows, macOS, Linux, other) + +Install Python with pip. Upgrade pip to a recent version using `python -m pip install --upgrade`. + +If you're on a supported version of Windows, macOS, or Linux (see the [HELICS PyPI page](https://pypi.org/project/helics/) for details) you can then use `pip` to install the HELICS Python interface and helics-apps. + +```bash +pip install helics +pip install helics-apps +``` + +If you are on an unsupported OS or Python version, you will need to install a copy of HELICS first. +Depending on your OS, there could be a copy in the package manager, or you may need to build HELICS from source. +From there, you can use `pip install helics` as above (NOTE: `pip install helics-apps` *will not work*, your package manager or HELICS build from source should install these). +The [source distributions section of the PyPI page](https://pypi.org/project/helics/) has some additional useful information on this process. diff --git a/docs/introduction/python.md b/docs/introduction/python.md index a26009c731..0380d9ad35 100644 --- a/docs/introduction/python.md +++ b/docs/introduction/python.md @@ -8,12 +8,10 @@ We will create a simple `pi-exchange` federation in Python with 2 federates. Before we run the Python `pi-exchange` federation, it is necessary to ensure that we have Python installed and that we have the HELICS Python built successfully and correctly on the machine. -We recommend using Anaconda3/Miniconda3, although this should work with most versions of Python. -To make an interface that is similar across different languages, we use SWIG to generate the Python bindings to the `helicsSharedLib` shared library. +We recommend using pip with Python (version 2.7 or 3.5+) or Anaconda3/Miniconda3 to install a copy of the HELICS Python interface, although this should work with most versions of Python if you build the interface yourself using SWIG to generate the Python bindings to the `helicsSharedLib` shared library. SWIG claims to be compatible with most Python versions, dating back to Python 2.0. And recommends that for the best results, one should consider using Python 2.3 or newer. -HELICS can also be built from source and linked with the required Python version. -See the page on the Installation instructions for more information regarding this. +See the Installation instructions page for more information regarding this. **Create a federations directory**