Update install instructions #832
Conversation
The installation file is very large and a bit confusing. We need to clean up a little. I started by clarifying the difference between the two presented methods and expanding the anaconda version.
INSTALL.md
Outdated
|
|
||
| Other required libraries will be installed automatically during the setup (listed in https://github.com/icecube/pisa/blob/master/setup.py). If something is missing, you can install it via pip afterwards. | ||
|
|
||
| 2. Create an environment for the installation of PISA (after activating anaconda). You can choose your preferred version of python >= 3.10. E.g. for miniconda with python 3.10 use: |
There was a problem hiding this comment.
This "preferred version of python >= 3.10" has somehow made it in here again, even though > isn't supported.
There was a problem hiding this comment.
Right, ideally we shouldn't give a version number here at all because that means we have to update the file regularly. However, we should rather work on the "doesn't work with python>3.10" issue
INSTALL.md
Outdated
|
|
||
| These are all run, plus additional tests (takes about 15-20 minutes on a laptop) with the command | ||
| ```bash | ||
| $PISA/pisa_tests/test_command_lines.sh |
There was a problem hiding this comment.
Have you looked at test_command_lines.sh? Many of the scripts it is trying to run don't exist or are broken. I would suggest running something else instead.
There was a problem hiding this comment.
I think readability can still be improved by enclosing shell variable names in the text body with backticks (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code), i.e. INSTALLER_VERSIONs etc.
There are incorrect statements in optional dependencies, such as where ROOT is required (xsec.genie doesn't exist any longer). I'm afraid we need to go through that list, update it, and consider whether really need/want to specify individual service names here (high maintenance cost).
|
|
||
| ## Instruction to install PISA using Anaconda or Miniconda | ||
|
|
||
| The following commands are intended for execution in a terminal. If you encounter any problems with the installation, please create an issue and/or ask on the IceCube slack (if possible). |
There was a problem hiding this comment.
Mention that commands assume bash shell (see https://github.com/icecube/pisa/blob/f8ce002424791a273c4bdea986a501e07418e25b/INSTALL.md).
| ``` | ||
| You can find a list of available INSTALLER_VERSIONs at https://repo.anaconda.com/miniconda/. | ||
|
|
||
| **If you install on the cobalts, rather use /data/user/YOURNAME/ than $HOME/ for PATH_TO_ANACONDA** |
There was a problem hiding this comment.
mention that "cobalts" are IceCube internal resources
|
|
||
| **If you install on the cobalts, rather use /data/user/YOURNAME/ than $HOME/ for PATH_TO_ANACONDA** | ||
|
|
||
| **Note** that you will also need git. It is already installed on the cobalts, ask your local system administrator if it is not on your local machine. The other non-python requirements are listed [here](https://github.com/icecube/pisa/blob/master/INSTALL.md#required-dependencies) and should already come with the conda environment. |
There was a problem hiding this comment.
remove "ask your local ..."
|
|
||
| **4.** Clone the PISA repository from github (https://github.com/icecube/pisa.git). You can also create your own fork first. For more information on how to obtain the pisa source code see [obtain-pisa-sourcecode](https://github.com/icecube/pisa/blob/master/INSTALL.md#obtain-pisa-sourcecode) | ||
|
|
||
| Define a directory for PISA sourcecode to live in. |
| Note that if files change names or locations, though, the above can still not be enough. | ||
| In this case, the old files have to be removed manually (along with any associated `.pyc` files, as Python will use these even if the `.py` files have been removed). | ||
|
|
||
|
|
||
| ### Compile the documentation | ||
|
|
||
| To compile a new version of the documentation to html (pdf and other formats are available by replacing `html` with `pdf`, etc.): |
There was a problem hiding this comment.
Is it true that html can simply be replaced by pdf? There is no "pdf" target in the Makefile produced by Sphinx (8.1.3 in my case). The Makefile we ship also doesn't contain this target.
Replace "(pdf and other formats are available by replacing html with pdf, etc.)" with "(run make help for other documentation formats)".
| conda activate NAME_OF_YOUR_PISA_ENV | ||
| ``` | ||
|
|
||
| **4.** Clone the PISA repository from github (https://github.com/icecube/pisa.git). You can also create your own fork first. For more information on how to obtain the pisa source code see [obtain-pisa-sourcecode](https://github.com/icecube/pisa/blob/master/INSTALL.md#obtain-pisa-sourcecode) |
There was a problem hiding this comment.
Replace "[obtain-pisa-sourcecode]" with "[below]" and use section link instead of URL (https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links). Add period to end of sentence.
| ```bash | ||
| git clone https://github.com/icecube/pisa.git | ||
| ``` | ||
| ### Reinstall PISA |
There was a problem hiding this comment.
I'd suggest moving the reinstallation guide to "additional information" (between "ensure a clean install ..." and "compile the documentation").
| ``` | ||
| - Run the pipeline | ||
| ```bash | ||
| $PISA/pisa/core/distribution_maker.py --pipeline settings/pipeline/IceCube_3y_neutrinos.cfg --outdir /tmp/pipeline_output --pdf |
There was a problem hiding this comment.
Simply call with pisa-distribution_maker --pipeline ... (see entry points in setup.py).
| template_maker.run() | ||
| ``` | ||
| - Get the oscillation probabilities as a map | ||
| #### Unit Tests |
There was a problem hiding this comment.
Not sure why this is part of installation guide. Remove.
|
|
||
| - Activate your python environment (`pisa_env`) | ||
| First activate your python environment (if not already active). Assuming you used Miniconda, you can do that with: | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
This activation code is copied and pasted from above. Remove and trust user to remember.
|
|
||
| ### Instructions to install PISA on Madison working group servers cobalts (current guide from August 2023): | ||
| ## Instructions to install PISA using cvmfs and virtual environment | ||
|
|
||
| Assuming you already are in the directory where you want to store fridge/pisa source files and the python virtualenv and build pisa. You also need access to github through your account. |
There was a problem hiding this comment.
Let's not deal with fridge here. For example, we just need the name of that repo to change for these instructions to be out of sync.
|
Let us remove the second set of cloning instructions in https://github.com/icecube/pisa/blob/d04604100703d9bf8c96d18863add362887e03b0/INSTALL.md#clone-into-the-fridge-and-pisa-ideally-your-own-fork. They're redundant (even though the first set in Line 61 in d046041 How to clone should be independent of whether the installation proceeds using miniconda or virtualenv. Look at this version of the guide, for example: can we not revert to some structure like that with universal instructions at the beginning, independent of whether the user decides to use conda or virtualenv? |
The installation file is very large and a bit confusing. We need to clean up a little. I started by clarifying the difference between the two presented methods and expanding the anaconda version.