From 09937c58c59523a55c8e725f94f0f4dc5c97e300 Mon Sep 17 00:00:00 2001 From: q-posev Date: Thu, 9 Sep 2021 15:06:26 +0200 Subject: [PATCH] better README --- python/README.md | 49 +++++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/python/README.md b/python/README.md index c43d260..c7c7b43 100644 --- a/python/README.md +++ b/python/README.md @@ -1,8 +1,8 @@ ## TREXIO Python API -TREXIO provides a Python API for interactive calls to the library. -It allows to simplify interfacing between different codes and can -be used to convert between different input/output file formats. +TREXIO provides a Python API, which enables interactive calls to the library. +It facilitates the development of interfaces between different codes and +can be used to convert data from one input/output file format into another. ### Requirements @@ -16,7 +16,8 @@ be used to convert between different input/output file formats. Run `pip3 install trexio` -**Note:** we highly recommend to use virtual environments to avoid compatibility issues. +**Note: we highly recommend to use virtual environments to avoid compatibility issues.** +For more details, see the corresponding part of the [Python documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments). ### Additional requirements (for installation from source) @@ -30,43 +31,45 @@ Run `pip3 install trexio` 1. Download the latest source code distribution (in `.tar.gz` format) of the TREXIO Python API 2. Unpack and `cd` in the output directory 3. Run `pip3 install -r requirements.txt` (this installs all python dependencies) -4. Run `pip3 install .` (this install `trexio` in your environment) -5. Run `cd test && python3 test_api.py` (this executes several tests that check the installation) +4. Run `pip3 install .` (this installs `trexio` in your environment) +5. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation) You are ready to go! ### Examples -An interactive Jupyter notebook called `tutorial_benzene.ipynb` can be found in the `examples` directory or on Binder (TODO: link). -It is provided to demonstrate some basic use cases of the TREXIO library in general and the Python API in particular. +An interactive Jupyter notebook called `tutorial_benzene.ipynb` is provided in the `examples` directory. +It demonstrates some basic use cases of the TREXIO library in general and of the Python API in particular. - -#### Additional requirements to run Jupyter notebooks with TREXIO - -Jupyter can be installed using `pip install jupyter`. - -If you have installed `trexio` in the virtual environemnt called, e.g. `myvenv`, make sure to also install it as a kernel for (this requires `ipykernel` python package to be installed) by executing the following: - -`python3 -m ipykernel install --user --name=myvenv` +Jupyter can be installed using `pip install jupyter`. If you are not familiar with it, feel free to consult the [Jupyter documentation](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html). #### Running the notebook -The example notebook can be launched using the following command +The example notebook can be launched using the following command: -`jupyter-notebook tutorial_benzene.ipynb` +`jupyter notebook tutorial_benzene.ipynb` -Once the notebook is open, make sure that your virtual environment is selected as the current kernel. -If this is not the case, try the following: + +#### Additional steps needed to run a custom virtual environment in Jupyter notebooks + +If you have installed `trexio` in a virtual environemnt called, e.g. `myvenv`, but would like to use your system-wide Jupyter installation, this is also possible. +This requires `ipykernel` python package to be installed, which usually comes together with the Jupyter installation. If this is not the case, run `pip install ipykernel`. +You can install `myvenv` as a kernel by executing the following command: + +`python3 -m ipykernel install --user --name=myvenv` + +Now you can launch a Jupyter notebook. Once it is open, make sure that your virtual environment is selected as the current kernel. +If this is not the case, try this: 1. Press the `Kernel` button in the navigation panel 2. In the output list of options select `Change kernel` 3. Find the name of your virtual environment (e.g. `myvenv`) in the list and select it -That's it, you have activated the virtual environment and can now run the cells of the `tutorial_benzene.ipynb` notebook. +That's it, you have activated the custom virtual environment called `myvenv` in your notebook. -To uninstall the kernel named `myvenv` from Jupyter, execute the following: +To uninstall the kernel named `myvenv`, execute the following command: -`jupyter kernelspec uninstall myvenv +`jupyter kernelspec uninstall myvenv`