search

ondrolexa / pywerami

Process contour data file generated by the Perple_X program WERAMI
Other
17 stars 2 forks source link

readme

pywerami

GitHub version Documentation Status DOI

What is pywerami

pywerami is a stand-alone program to make an countour/3D plot from data file generated by the Perple_X program WERAMI or tci file generated by TCInvestigator.

Installation

pywerami can be installed as a Python package on Windows, Linux, Mac OS X, and Mac OS Apple Silicon.

You need Python 3.6 or later to run pywerami. The package requires NumPy and SciPy, and the plotting routines require Matplotlib, so we strongly recommend using Miniforge to install it in its own isolated environment.

The newest version of pywerami can always be found in the Releases page.

Installation requires entering commands in a terminal. To open one:

Windows: Open the Start menu and search for the Miniforge Prompt (if using Miniforge) or the Command Prompt if not.

Linux: Launch a new terminal by pressing Ctrl + Alt + T.

Mac: Launch a new terminal by pressing Cmd + Space and searching for Terminal.

Installing Miniforge

Miniforge is the minimal installers for Conda and Mamba specific to conda-forge, with the pre-configured conda-forge channel as the default (and only) channel.

If you already have Anaconda on your computer, then you can set the solver to libmamba in the base environment (and skip the Miniforge installation):

conda update -n base conda
conda install -n base conda-libmamba-solver
conda config --set solver libmamba
Any subsequent `mamba` commands in the docs will need to be replaced with `conda` if you choose to use your existing Anaconda installation.

Otherwise, to install Mamba:

On Windows, just click through the installation steps.

  1. Go to: https://github.com/conda-forge/miniforge#download
  2. Download the latest version for your OS.
  3. Follow the installer instructions.

We recommend using the following settings:

On Linux, it might be easier to do this straight from the terminal (Ctrl + Alt + T) with this one-liner:

wget -nc https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh && bash Mambaforge-Linux-x86_64.sh -b && ~/mambaforge/bin/conda init bash

Restart the terminal after running this command.

For other Linux architectures (arm64 and POWER8/9), replace the .sh filenames above with the correct installer name for your architecture. See the Download column in this table for the correct filename.

On Macs (pre-M1), you can run the installer using this terminal command:

wget -nc https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh && bash Miniforge3-MacOSX-x86_64.sh -b && ~/mambaforge/bin/conda init zsh

On Macs (Apple Silicon), use this terminal command:

curl -fsSL --compressed https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh -o Miniforge3-MacOSX-arm64.sh && chmod +x Miniforge3-MacOSX-arm64.sh && ./Miniforge3-MacOSX-arm64.sh -b -p ~/mambaforge && rm Miniforge3-MacOSX-arm64.sh && ~/mambaforge/bin/conda init "$(basename "${SHELL}")" && source "$HOME/.$(basename "${SHELL}")rc"

Installation methods

pywerami could be installed using pip two different ways:

Using pip package

Although you do not need Mambaforge installed to perform a pip install, we recommend {ref}installing Mambaforge<mambaforge> to create a new environment where we can isolate the pip install. Alternatively, you can use a venv if you have an existing python installation.

  1. Create the environment to isolate the pip install from other environments on your computer:

    mamba create -y -n pywerami python=3 pyqt=5 numpy matplotlib scipy

  2. Activate the environment:

    mamba activate pywerami

    Refrain from installing anything into the base environment. Always create a new environment to install new packages.

  3. Finally, we can perform the pip install:

    pip install pywerami

    This is the recommended installation method.

Using pip from source

  1. Download zip source from Releases page or download master version. Unzip the folder, open terminal and change directory to unzipped folder.

  2. Create separate environment with all requirements:

    mamba env create -f environment.yml

  3. Finally, we can perform the pip install:

    pip install .

    This is the recommended method for development.

Testing that things are working

If you installed using mamba, first activate the pywerami environment by opening a terminal and typing:

mamba activate pywerami

Not sure what mamba environments you already installed? You can get a list of the environments on your system with:

mamba env list

to start pywerami, simply type:

pywerami

Upgrading and uninstalling

We strongly recommend installing pywerami in a fresh environment when updating. This is because dependency versions might change, and depending on the state of your previous environment, directly updating might break compatibility with some of them.

To uninstall an existing environment named sleap:

mamba env remove -n pywerami

Once the environment has been removed, you are free to install pywerami using any of the installation methods above into an environment of the same name.

Getting help

If you get any errors open a new Issue providing the versions from either command above, as well as any errors you saw in the console during the installation.

Donate

pywerami is an open-source project, available for you for free. It took a lot of time and resources to build this software. If you find this software useful and want to support its future development please consider donating me.

Donate via PayPal

License

pywerami is free software: you can redistribute it and/or modify it under the terms of the MIT License. A copy of this license is provided in LICENSE file.