SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/Tutorials - Python.md Hit Total Coverage
Commit: 2db722c93a8e9b106e406b439b79c8e05c2057fb Lines: 0 1 0.0 %
Date: 2021-03-03 22:01:00
Legend: Lines: hit not hit

          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             : Some classes and functions from SpECTRE have Python bindings to make it easier
       8             : to visualize data, write test code, and provide an introduction to numerical
       9             : relativity without needing to delve into C++.
      10             : 
      11             : ## Installing the SpECTRE Python modules
      12             : 
      13             : First, build SpECTRE with Python bindings enabled by appending the
      14             : `-D BUILD_PYTHON_BINDINGS=ON` flag to the `cmake` command. You can specify the
      15             : Python version, interpreter and libraries used for compiling and testing the
      16             : bindings by setting the `-D Python_EXECUTABLE` to an absolute path such as
      17             : `/usr/bin/python3`. You will find that
      18             : a `BUILD_DIR/bin/python` directory is created that contains the Python modules.
      19             : Then, you can install the modules into your Python environment in
      20             : _development mode_, which means they are symlinked so that changes to the
      21             : modules will be reflected in your Python environment, with the command
      22             : `pip install -e path/to/bin/python`. Alternatively, remove the `-e` flag to
      23             : install the modules normally. You can do this in any Python environment that
      24             : supports `pip`, for instance in a
      25             : [`virtualenv`/`venv`](https://docs.python.org/3/tutorial/venv.html) or in an
      26             : [Anaconda](https://www.anaconda.com/distribution/) environment. You can also get
      27             : access to the SpECTRE Python modules by adding  `BUILD_DIR/bin/python` to your
      28             : `PYTHONPATH`. This is done automatically by sourcing the `LoadPython.sh` file
      29             : with the command `. BUILD_DIR/bin/LoadPython.sh`. By default, SpECTRE uses
      30             : `jemalloc` which needs to be pre-loaded for the python bindings to work.
      31             : Therefore, you need to run `LD_PRELOAD=/path/to/libjemalloc.so python`
      32             : to execute python scripts or start python consoles. The path to your preferred
      33             : jemalloc installation is printed out at the end of the `cmake`
      34             : configuration or can be found by running the script
      35             : `BUILD_DIR/bin/LoadPython.sh`. Alternatively, you can use your system's memory
      36             : allocator by appending the flag `-D MEMORY_ALLOCATOR=SYSTEM` to the `cmake`
      37             : command. In this case you will not need to pre-load any libraries.
      38             : 
      39             : ## Running Jupyter within the Docker container
      40             : 
      41             : [Jupyter lab](https://jupyterlab.readthedocs.io/) is installed in the Docker
      42             : container. You can run it in the container and access it through a browser on
      43             : the host for a convenient way to work with the SpECTRE Python bindings. To do
      44             : so, make sure you have exposed a port when running the Docker container, e.g.
      45             : by appending the option `-p 8000:8000` to the `docker run` command (see
      46             : \ref installation). Inside the docker container, it can be convenient to
      47             : use `disown` or to `apt-get install screen` and use `screen` to obtain a shell
      48             : that runs the Jupyter server permanently in the background. Within the shell you
      49             : want to run your Jupyter server, navigate to a directory that will serve as the
      50             : root for the file system that Jupyter has access to. Make sure it is shared with
      51             : the host (e.g. `SPECTRE_HOME`) so your Jupyter notebooks are not lost when the
      52             : container is deleted. Then, run the following command:
      53             : 
      54             : ```sh
      55             : jupyter lab --ip 0.0.0.0 --port 8000 --allow-root
      56             : ```
      57             : 
      58             : Copy the token that is being displayed. Now you can open a browser on the host
      59             : machine, point it to `http://localhost:8000` and paste in the token. You will
      60             : have access to the Python environment within the Docker container. If you have
      61             : followed the instructions above for installing the SpECTRE Python package,
      62             : you can try importing the Python package in a notebook with:
      63             : 
      64             : ```py
      65             : import spectre
      66             : ```
      67             : 
      68             : While developing Python code in the `spectre` packages it can be useful to
      69             : configure Jupyter to reload packages when they change. Add the following code
      70             : before any import statements:
      71             : 
      72             : ```
      73             : %load_ext autoreload
      74             : %autoreload 2
      75             : ```

Generated by: LCOV version 1.14