Commit f0192806 authored by David Moxey's avatar David Moxey

Update documentation

parent cd69ead1
......@@ -6,8 +6,8 @@ _experimental_ and _incomplete_.** You should not rely on their current
structure and API remaining unchanged.
Currently, representative classes from the `LibUtilities`, `StdRegions`,
`SpatialDomains` and `LocalRegions` libraries have been wrapped in order to show
the proof-of-concept.
`SpatialDomains`, `LocalRegions` and `MultiRegions` libraries have been wrapped
in order to show the proof-of-concept.
# Features and functionality
......@@ -29,45 +29,43 @@ fx = np.sin(x) * np.cos(y)
proj = quadExp.FwdTrans(fx)
```
`NekPy` uses the `Boost.NumPy` library, contained in Boost 1.63+, to
automatically convert C++ `Array<OneD, >` objects to and from the commonly-used
`numpy.ndarray` object, which makes the integration more seamless between Python
and C++.
This example shows how to create a `StdQuadExp` and perform a rudimentary
forwards transform using the `NekPy` wrappers.
`NekPy` additionally uses the `Boost.NumPy` library, contained in Boost 1.63+,
to automatically convert C++ `Array<OneD, T>` objects to and from the
commonly-used `numpy.ndarray` object, which makes the integration more seamless
between Python and C++.
# How do I wrap things?
`Boost.Python` is a pretty comprehensive package and an extended discussion is
really beyond the scope of this project. See `doc/wrapping-guide.md` for some
basic concepts and frequently-encountered issues.
really beyond the scope of this project. See [the wrapping
guide](wrapping-guide.md) for some basic concepts and frequently-encountered
issues.
# Compiling
NekPy has the following list of requirements:
- Boost with Python support
- Nektar++ `master` branch compiled from source (i.e. not from packages)
- Python 2.7+ (note that examples rely on Python 2.7)
- NumPy
- Python 2.7+
- NumPy, installed either from your package manager or through `pip`.
Most of these can be installed using package managers on various operating
systems, as we describe below. We also have a requirement on the `Boost.NumPy`
package, which is available in boost 1.63 or later. If this isn't found on your
system, it will be automatically downloaded and compiled.
## Compiling and installing Nektar++
Nektar++ should be compiled as per the user guide instructions and installed
into a directory which we will refer to as `$NEKDIR`. By default this is the
`dist` directory inside the Nektar++ build directory.
## Compiling and installing Nektar++ with NekPy support
Note that Nektar++ must, at a minimum, be compiled with `NEKTAR_BUILD_LIBRARY`,
`NEKTAR_BUILD_UTILITIES` , `NEKTAR_BUILD_SOLVERS` and `NEKTAR_BUILD_PYTHON`.
This will automatically download and install `Boost.NumPy` if required. Note
that all solvers may be disabled as long as the `NEKTAR_BUILD_SOLVERS` option is set.
Nektar++ should be compiled as per the user guide instructions. To build the
`NekPy` wrapper, you should ensure that the `NEKTAR_BUILD_PYTHON` option is
enabled.
## macOS
### macOS
### Homebrew
#### Homebrew
Users of Homebrew should make sure their installation is up-to-date with `brew
upgrade`. Then run
......@@ -81,7 +79,7 @@ To install the NumPy package, use the `pip` package manager:
pip install numpy
```
### MacPorts
#### MacPorts
Users of MacPorts should sure their installation is up-to-date with `sudo port
selfupdate && sudo port upgrade outdated`. Then run
......@@ -92,7 +90,7 @@ sudo port select --set python python27
```
## Linux: Ubuntu/Debian
### Linux: Ubuntu/Debian
Users of Debian and Ubuntu Linux systems should sure their installation is
up-to-date with `sudo apt-get update && sudo apt-get upgrade`
......@@ -101,9 +99,9 @@ up-to-date with `sudo apt-get update && sudo apt-get upgrade`
sudo apt-get install libboost-python-dev python-numpy
```
## Compiling the wrappers
## Installing the wrappers
Run the following command in `$NEKDIR\build` directory to install the Python package
Run the following command in `$NEKDIR/build` directory to install the Python package
for the current user:
```
......@@ -120,7 +118,7 @@ make nekpy-install-system
# Using the bindings
By default, the bindings will install into the `dist` directory, along with a
number of examples that are stored in the `$NEKDIR\library\Demos\Python` directory. To
number of examples that are stored in the `$NEKDIR/library/Demos/Python` directory. To
test your installation, you can for example run one of these (e.g. `python Basis.py`) or
launch an interactive session:
......@@ -137,7 +135,7 @@ Type "help", "copyright", "credits" or "license" for more information.
## Examples
A number of examples of the wrappers can be found in the `$NEKDIR\library\Demos\Python`
A number of examples of the wrappers can be found in the `$NEKDIR/library/Demos/Python`
directory, along with a sample mesh `newsquare_2x2.xml`:
- `SessionReader.py` is the simplest example and shows how to construct a
......@@ -151,5 +149,5 @@ directory, along with a sample mesh `newsquare_2x2.xml`:
quadrilateral elements. Run it as `python MeshGraph.py newsquare_2x2.xml`.
If you want to modify the source files, it's advisable to edit them in the
`$NEKDIR\library\Demos\Python` directory and re-run `make install`, otherwise local
`$NEKDIR/library/Demos/Python` directory and re-run `make install`, otherwise local
changes will be overwritten by the next `make install`.
......@@ -75,7 +75,8 @@ the different classes into different files, because it is not possible to call
`BOOST_PYTHON_MODULE` more than once. These functions are defined in
appropriately named files, for example:
- `export_Basis()` lives in the file `NekPy/LibUtilities/Foundations/Basis.cpp`
- `export_Basis()` lives in the file
`library/LibUtilities/Python/Foundations/Basis.cpp`
- This corresponds to the Nektar++ file
`library/LibUtilities/Foundations/Basis.cpp` and the classes defined therein.
......@@ -197,9 +198,10 @@ these as parameters and return arrays very easily. However bear in mind the
following caveats:
- NumPy arrays created from Array objects will share their memory, so that
changing the C++ array changes the contents of the NumPy array. However, due
to limitations of the Array class, the converse is _not true_: Arrays are
always copies of NumPy arrays.
changing the C++ array changes the contents of the NumPy array. Likewise, C++
arrays created from NumPy arrays will share memory. Reference counting and
capsules are used to ensure that memory should be persistent whilst the arrays
are in use, either within Python or C++.
- Many functions in Nektar++ return Arrays through argument parameters. In
Python this is a very unnatural way to write functions. For example:
```python
......@@ -212,7 +214,7 @@ following caveats:
Use thin wrappers to overcome this problem. For examples of how to do this,
particularly in returning tuples, consult the `StdRegions/StdExpansion.cpp`
wrapper.
- `TwoD` and `ThreeD` arrays are not supported.
- `TwoD` and `ThreeD` arrays are not presently supported.
## Inheritance
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment