TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2025-01-08 20:33:36 +01:00
Code Issues Projects Releases Wiki Activity

better README

Browse Source
This commit is contained in:
q-posev 2021-09-09 15:06:26 +02:00
parent b9bbf178c5
commit 09937c58c5
1 changed files with 26 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
python/README.md
View File

@ -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`