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             : ## Installing the SpECTRE Python modules
      14             : 
      15             : First, build SpECTRE with Python bindings enabled by appending the
      16             : `-D BUILD_PYTHON_BINDINGS=ON` flag to the `cmake` command (enabled by default).
      17             : You can specify the
      18             : Python version, interpreter and libraries used for compiling and testing the
      19             : bindings by setting the `-D Python_EXECUTABLE` to an absolute path such as
      20             : `/usr/bin/python3`. Compile the `all-pybindings` (or `cli`) target. You will
      21             : find that a `BUILD_DIR/bin/python` directory is created that contains the
      22             : Python modules. Then, you can install the modules into your Python environment
      23             : in _development mode_, which means they are symlinked so that changes to the
      24             : modules will be reflected in your Python environment, with the command
      25             : `pip install -e path/to/bin/python`. Alternatively, remove the `-e` flag to
      26             : install the modules normally. You can do this in any Python environment that
      27             : supports `pip`, for instance in a
      28             : [`virtualenv`/`venv`](https://docs.python.org/3/tutorial/venv.html) or in an
      29             : [Anaconda](https://www.anaconda.com/distribution/) environment. You can also get
      30             : access to the SpECTRE Python modules by adding  `BUILD_DIR/bin/python` to your
      31             : `PYTHONPATH`. This is done automatically by sourcing the `LoadPython.sh` file
      32             : with the command `. BUILD_DIR/bin/LoadPython.sh`.
      33             : 
      34             : Try running the main entrypoint:
      35             : 
      36             : ```sh
      37             : # In the build directory:
      38             : ./bin/spectre --help
      39             : # Or, if you have (pip-)installed the package:
      40             : spectre --help
      41             : ```
      42             : 
      43             : The SpECTRE Python package supports autocompletion for Bash, Zsh, and Fish.
      44             : Depending on your shell, source the corresponding file:
      45             : 
      46             : ```sh
      47             : # In the build directory:
      48             : # - Bash:
      49             : . ./bin/python/shell-completion.bash
      50             : # - Fish:
      51             : cp ./bin/python/shell-completion.fish ~/.config/fish/completions/spectre.fish
      52             : # - Zsh:
      53             : . ./bin/python/shell-completion.zsh
      54             : ```
      55             : 
      56             : You may want to source the shell completion script on startup, e.g., in your
      57             : `.bashrc` or `.zshrc` file.
      58             : 
      59             : By default, SpECTRE uses
      60             : `jemalloc` which needs to be pre-loaded for the python bindings to work.
      61             : Therefore, you need to run `LD_PRELOAD=/path/to/libjemalloc.so python`
      62             : to execute python scripts or start python consoles. The path to your preferred
      63             : jemalloc installation is printed out at the end of the `cmake`
      64             : configuration or can be found by running the script
      65             : `BUILD_DIR/bin/LoadPython.sh`. Alternatively, you can use your system's memory
      66             : allocator by appending the flag `-D MEMORY_ALLOCATOR=SYSTEM` to the `cmake`
      67             : command. In this case you will not need to pre-load any libraries.
      68             : 
      69             : ## Running Jupyter within the Docker container
      70             : 
      71             : [Jupyter lab](https://jupyterlab.readthedocs.io/) is installed in the Docker
      72             : container. You can run it in the container and access it through a browser on
      73             : the host for a convenient way to work with the SpECTRE Python bindings. To do
      74             : so, make sure you have exposed a port when running the Docker container, e.g.
      75             : by appending the option `-p 8000:8000` to the `docker run` command (see
      76             : \ref installation). Inside the docker container, it can be convenient to
      77             : use `disown` or to `apt-get install screen` and use `screen` to obtain a shell
      78             : that runs the Jupyter server permanently in the background. Within the shell you
      79             : want to run your Jupyter server, navigate to a directory that will serve as the
      80             : root for the file system that Jupyter has access to. Make sure it is shared with
      81             : the host (e.g. `SPECTRE_HOME`) so your Jupyter notebooks are not lost when the
      82             : container is deleted. Then, run the following command:
      83             : 
      84             : ```sh
      85             : jupyter lab --ip 0.0.0.0 --port 8000 --allow-root
      86             : ```
      87             : 
      88             : Copy the token that is being displayed. Now you can open a browser on the host
      89             : machine, point it to `http://localhost:8000` and paste in the token. You will
      90             : have access to the Python environment within the Docker container. If you have
      91             : followed the instructions above for installing the SpECTRE Python package,
      92             : you can try importing the Python package in a notebook with:
      93             : 
      94             : ```py
      95             : import spectre
      96             : ```
      97             : 
      98             : While developing Python code in the `spectre` packages it can be useful to
      99             : configure Jupyter to reload packages when they change. Add the following code
     100             : before any import statements:
     101             : 
     102             : ```
     103             : %load_ext autoreload
     104             : %autoreload 2
     105             : ```