Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : # Using SpECTRE's Python modules {#spectre_using_python}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : Some classes and functions from SpECTRE have Python bindings to make it easier
      10             : to visualize data, write test code, and provide an introduction to numerical
      11             : relativity without needing to delve into C++.
      12             : 
      13             : ## Building the SpECTRE Python modules
      14             : 
      15             : > tl;dr: Compile the `all-pybindings` or `cli` target.
      16             : 
      17             : First, build SpECTRE with Python bindings enabled by appending the
      18             : `-D BUILD_PYTHON_BINDINGS=ON` flag to the `cmake` command (enabled by default).
      19             : You can specify the
      20             : Python version, interpreter and libraries used for compiling and testing the
      21             : bindings by setting the `-D Python_EXECUTABLE` to an absolute path such as
      22             : `/usr/bin/python3`. Compile the `all-pybindings` (or `cli`) target. You will
      23             : find that a `BUILD_DIR/bin/python` directory is created that contains the
      24             : Python modules.
      25             : 
      26             : ## Importing the SpECTRE Python modules
      27             : 
      28             : > tl;dr: Spin up a Jupyter notebook with `./bin/python-spectre -m jupyterlab`,
      29             : > then `import spectre`.
      30             : 
      31             : You have many options for making the Python modules accessible to import in your
      32             : scripts:
      33             : 
      34             : - Use the `BUILD_DIR/bin/python-spectre` shortcut to run your scripts. It just
      35             :   points the `PYTHONPATH` to the modules in `BUILD_DIR/bin/python` and invokes
      36             :   the Python interpreter that you configured your build with. You can also use
      37             :   this shortcut to spin up a Jupyter server:
      38             : 
      39             :   ```sh
      40             :   BUILD_DIR/bin/python-spectre -m jupyterlab
      41             :   ```
      42             : 
      43             :   If Jupyter is not yet installed in your Python environment, you can install it
      44             :   like this:
      45             : 
      46             :   ```sh
      47             :   BUILD_DIR/bin/python-spectre -m pip install jupyterlab
      48             :   ```
      49             : 
      50             :   > Note for VSCode users: You can also select this Jupyter server as kernel for
      51             :   > notebooks running in VSCode (see [docs](https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_connect-to-a-remote-jupyter-server)).
      52             : 
      53             : - Install the modules into your Python environment:
      54             : 
      55             :   ```sh
      56             :   pip install [-e] BUILD_DIR/bin/python
      57             :   ```
      58             : 
      59             :   The optional `-e` flag installs the modules in _development mode_, which means
      60             :   they are symlinked so that changes to the modules will be reflected in your
      61             :   Python environment.
      62             : 
      63             :   You can install the Python modules like this in any Python environment that
      64             :   supports `pip`, for instance in a
      65             :   [`virtualenv`/`venv`](https://docs.python.org/3/tutorial/venv.html) or in an
      66             :   [Anaconda](https://www.anaconda.com/distribution/) environment.
      67             : 
      68             : - You can also get access to the SpECTRE Python modules by manually adding
      69             :   `BUILD_DIR/bin/python` to your `PYTHONPATH`. This is done automatically by
      70             :   the `LoadPython.sh` script:
      71             : 
      72             :   ```sh
      73             :   . BUILD_DIR/bin/LoadPython.sh
      74             :   ```
      75             : 
      76             : Using any of the above options you should be able to import the `spectre` Python
      77             : modules in your scripts or notebooks. You can try it like this:
      78             : 
      79             : ```py
      80             : import spectre
      81             : ```
      82             : 
      83             : For an overview of all available Python modules see the
      84             : [Python modules documentation](py/_autosummary/spectre.html). For an example
      85             : what you can do with them see the tutorial on \ref tutorial_vis_python.
      86             : 
      87             : ## Running Jupyter within the Docker container
      88             : 
      89             : You can run [Jupyter lab](https://jupyterlab.readthedocs.io/) in the Docker
      90             : container and access it through a browser on
      91             : the host for a convenient way to work with the SpECTRE Python bindings. To do
      92             : so, make sure you have exposed a port when running the Docker container, e.g.
      93             : by appending the option `-p 8000:8000` to the `docker run` command (see
      94             : \ref installation). Inside the docker container, it can be convenient to
      95             : use `disown` or to `apt-get install screen` and use `screen` to obtain a shell
      96             : that runs the Jupyter server permanently in the background. Within the shell you
      97             : want to run your Jupyter server, navigate to a directory that will serve as the
      98             : root for the file system that Jupyter has access to. Make sure it is shared with
      99             : the host (e.g. `SPECTRE_HOME`) so your Jupyter notebooks are not lost when the
     100             : container is deleted. Then, run the following command:
     101             : 
     102             : ```sh
     103             : BUILD_DIR/bin/python-spectre -m jupyterlab --ip 0.0.0.0 --port 8000 --allow-root
     104             : ```
     105             : 
     106             : Copy the token that is being displayed. Now you can open a browser on the host
     107             : machine, point it to `http://localhost:8000` and paste in the token. You will
     108             : have access to the Python environment within the Docker container.
     109             : 
     110             : ## Developing Python code
     111             : 
     112             : > tl;dr: Set `PY_DEV_MODE=ON` in your CMake configuration so Python files are
     113             : > symlinked to the build directory.
     114             : 
     115             : When you edit any of the Python files in the repository, the changes are not
     116             : immediately reflected in the Python modules that you import from the build
     117             : directory. You have to run `cmake .` in the build directory to update the Python
     118             : files. This can be avoided by setting `cmake -D PY_DEV_MODE=ON .` in the build
     119             : directory, which configures CMake to symlink the Python files rather than copy
     120             : them. Some features that rely on CMake variables break with this mode, e.g. the
     121             : SpECTRE version number is not inserted into the Python modules so
     122             : `spectre.__version__` will return nonsense. Nonetheless, enabling this mode
     123             : avoids a lot of the hassle that comes from re-configuring CMake every time you
     124             : change a file.
     125             : 
     126             : Furthermore, enabling `autoreload` in Jupyter notebooks can be very helpful when
     127             : you are editing Python code. Add the following code before any import statements
     128             : in your notebook:
     129             : 
     130             : ```
     131             : %load_ext autoreload
     132             : %autoreload 2
     133             : ```
     134             : 
     135             : For details on writing Python bindings for our C++ functions, rather than
     136             : writing Python code, see the developer guide on
     137             : \ref spectre_writing_python_bindings.