TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-12-23 04:43:57 +01:00
Code Issues Projects Releases Wiki Activity

better documentation

Browse Source
This commit is contained in:
q-posev 2021-09-09 17:29:17 +02:00
parent 569fac5578
commit dcfe1da870
3 changed files with 16 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
python/README.md
View File

@ -31,8 +31,12 @@ For more details, see the corresponding part of the [Python documentation](https
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 installs `trexio` in your environment)
5. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation)
4. Export custom environment variables needed for the installation. Steps 1 and 2 can be skipped if HDF5 is properly configured for `pkg-config` (i.e. if executing `pkg-config --libs hdf5` returns a list of options).
1. `export H5_CFLAGS=-I/path/to/hdf5/include`
2. `export H5_LDFLAGS=-L/path/to/hdf5/lib`
3. `source tools/set_NUMPY_INCLUDEDIR.sh`
5. Run `pip3 install .` (this installs `trexio` in your environment)
6. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation)
You are ready to go!
@ -54,8 +58,9 @@ The example notebook can be launched using the following command:
#### 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`.
In some cases, it may happen that the Jupyter kernels in the activated virtual environment (e.g. `myvenv`) still point to the system-wide python binaries and not to the environment ones.
This will result in `ImportError` when importing `trexio` in the notebook cell. In order to avoid this, the `myvenv` has to be installed as an additional kernel.
This requires `ipykernel` python package, 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`

24
python/README_SETUP.txt
View File

@ -1,24 +0,0 @@
# Additional information related to the installation of the TREXIO Python API
Removing MANIFEST.in leads to issues in the installation. In particular, the .c and .h source files do not get copied
from the src/ directory into the tar.gz which is produced by setup sdist command.
These source files are required to build the pytrexio.so extension module, which is needed for the Python API.
Then the following commands do the job of installing trexio in virtual environment:
$ python3 -m pip install --upgrade setuptools wheel twine
$ python3 -s setup.py --no-user-cfg build
$ python3 setup.py sdist bdist_wheel
$ python3 -m pip install dist/trexio-0.1-*.whl --force-reinstall
BUG: when trying to install trexio from tar.gz, trexio appears to be installed
after user runs [python3 -s setup.py --no-user-cfg build]
but before [python3 -m pip install dist/{WHEELNAME}.whl]
which leads to pip install saying that trexio is already installed but the test fails saying that _trexio was not found,
indicating that probably first installation did not go well.
FIX: Use --force-reinstall option with pip install
The installed in virtual environment trexio can be uninstalled using [pip uninstall trexio]
but only from the root directory where the initially used (to install) setup.py script is located.
For example, it is most probably the python/ directory of the TREXIO_ROOT folder.

18
python/install_pytrexio.sh
View File

@ -6,8 +6,6 @@ set -e
H5_CFLAGS_LOCAL=$1
H5_LDFLAGS_LOCAL=$2
# This script should update the version of the Python package
#source version.py
# Install/upgrade packages required for the installation
python3 -m pip install --upgrade setuptools wheel twine
@ -33,23 +31,21 @@ python3 -m pip install dist/trexio-*.whl --force-reinstall
# Run the command below in the root directory to install the package in 'editable' (-e) mode without dependencies (--no-deps)
#python -m pip install -e . --no-deps
# Uninstall pytrexio: this only works from the pytrexio root directory (more likely python/ folder) and only after --force-reinstall
# Uninstall pytrexio: this only works from the pytrexio root directory
#python3 -m pip uninstall trexio
# Test the current release by uploading to TestPyPI sandbox
#python3 -m twine upload --repository testpypi dist/trexio-*.tar.gz
# NOTE:I get an error:
# Binary wheel 'trexio-0.1-cp38-cp38-linux_x86_64.whl' has an unsupported platform tag 'linux_x86_64'.
# when uploading the wheel instead of the tar.gz file to testpypi
# This is a well-known issue, see https://stackoverflow.com/questions/59451069/binary-wheel-cant-be-uploaded-on-pypi-using-twine
# Once fixed both .tar.gz and .whl distribution can be uploaded, meaning that dist/trexio-*.tar.gz can be replaced by dist/*
#
# Compatibility tags for Linux have been discussed in PEP-513 https://www.python.org/dev/peps/pep-0513/
# Upload updated version of PyTREXIO to PyPI
#python3 -m twine upload dist/trexio-*.tar.gz
# Cleaning
rm -rf build dist trexio.egg-info
# Additional information related to the installation of the TREXIO Python API
#Removing MANIFEST.in leads to issues in the installation. In particular, the .c and .h source files do not get copied
#from the src/ directory into the tar.gz which is produced by setup sdist command.
#These source files are required to build the pytrexio.so extension module, which is needed for the Python API.