Conda/Python Package Process Creation and CI

.github/workflows/actions.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [next]
+    tags: ['v*']
+
+jobs:
+  conda-build:
+      runs-on: ubuntu-latest
+      defaults:
+        run:
+          shell: bash -l {0}
+      steps:
+        - uses: actions/checkout@v4
+        - uses: mamba-org/setup-micromamba@v1
+          with:
+            environment-file: environment.yml
+            cache-environment-key: ${{ runner.os }}-env-${{ hashFiles('**/environment.yml') }}
+            cache-downloads-key: ${{ runner.os }}-downloads-${{ hashFiles('**/environment.yml') }}
+            condarc: |
+              channels:
+                - conda-forge
+                - pytorch
+                - pyg
+        - name: building python wheel
+          shell: bash -l {0}
+          run: |
+            python -m build --wheel --no-isolation
+            check-wheel-contents dist/inspired-*.whl
+        - name: build conda package
+          shell: bash -l {0}
+          run: |
+            # set up environment
+            cd conda.recipe
+            echo "versioningit $(versioningit ../)"
+            # build the package
+            CHANNELS="--channel conda-forge --channel pytorch --channel pyg"
+            VERSION=$(versioningit ../) conda mambabuild $CHANNELS --output-folder . .
+            conda verify noarch/inspired*.tar.bz2
+        - name: upload conda package to anaconda
+          shell: bash -l {0}
+          if: startsWith(github.ref, 'refs/tags/v')
+          env:
+            ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_TOKEN }}
+            IS_RC: ${{ contains(github.ref, 'rc') }}
+          run: |
+            # label is main or rc depending on the tag-name
+            CONDA_LABEL="main"
+            if [ "${IS_RC}" = "true" ]; then CONDA_LABEL="rc"; fi
+            echo pushing ${{ github.ref }} with label $CONDA_LABEL
+            anaconda upload --label $CONDA_LABEL conda.recipe/noarch/inspired*.tar.bz2

.gitignore

@@ -0,0 +1,163 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_version.py
+conda.recipe/*
+!conda.recipe/meta.yaml
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.envrc

README.md

@@ -8,7 +8,7 @@ INSPIRED is a PyQt GUI that performs rapid prediction/calculation/visualization
 
 * Pros: any structure, minimum parameter setting, very fast (seconds)
 
-* Cons: powder samples only, predefined Q and E ranges, less accurate
+* Cons: powder samples only, predefined Q and E ranges, less accurate, accuracy varies significantly from case to case
 
   ![image](https://github.com/cyqjh/inspired/assets/105002220/2fd4288e-2739-4852-9d4e-4513c9cfc029)
 
@@ -26,7 +26,7 @@ INSPIRED is a PyQt GUI that performs rapid prediction/calculation/visualization
 
 * Pros: any structure, both powder and single crystal samples
 
-* Cons: can be slow for large or low-symmetry systems, accuracy varies significantly from case to case (see Additional notes)
+* Cons: can be slow for large or low-symmetry systems, accuracy varies significantly from case to case
 
   ![image](https://github.com/cyqjh/inspired/assets/105002220/04571dc1-5dfb-469b-92e9-8e5f523b33d2)
 
@@ -35,7 +35,15 @@ INSPIRED is a PyQt GUI that performs rapid prediction/calculation/visualization
 
 ## Installation:
 
-For most users, the easiest way to use INSPIRED is to download a pre-installed VirtualBox image and run INSPIRED as a virtual machine (VM) on any platform, including Windows, MacOS, and Linux ([Option 1](https://github.com/cyqjh/inspired#option-1)). If you have acess to a Linux machine (such as the [Analysis cluster](https://analysis.sns.gov/)) and would like to have a native installation, you may also do so ([Option 2](https://github.com/cyqjh/inspired#option-2)).
+INSPIRED is available on the [Analysis cluster](https://analysis.sns.gov/) as a conda environment. To run INSPIRED, all you need to do is to activate "inspired-dev" in the global conda environment:
+
+`source /opt/anaconda/etc/profile.d/conda.sh`
+
+`conda activate inspired-dev`
+
+`inspired`
+
+To use INSPIRED on another computer, there are two installation options. One option is to download a pre-installed VirtualBox image and run INSPIRED as a virtual machine (VM) on any platform, including Windows, MacOS, and Linux ([Option 1](https://github.com/cyqjh/inspired#option-1)). If you have acess to a Linux machine and would like to have a native installation, you may also do so ([Option 2](https://github.com/cyqjh/inspired#option-2)).
 
 ### Option 1
 1. Install [VirtualBox for your operating system](https://www.virtualbox.org/wiki/Downloads). Unfortunately, VirtualBox does not support Apple M3 chips. There was a [developer preview](https://download.virtualbox.org/virtualbox/7.0.8/VirtualBox-7.0.8_BETA4-156879-macOSArm64.dmg) from an older version of VirtualBox that may support M1/M2 chips, but we did not test it. We are working on a solution to address this issue.
@@ -68,15 +76,7 @@ For most users, the easiest way to use INSPIRED is to download a pre-installed V
 
    Press Ctrl+S to save and Ctrl+X to exit (if using nano). This folder will now be automatically mounted when you run the VM on this computer.
 
-7. Update the code/model to the newest version by running:
-
-   `cd /home/inspired/inspired`
-
-   `git pull`
-
-     This step is important as the VM may not contain the newest version of INSPIRED. It is also recommended that you run this regularly to ensure you get the latest bug fixes. The database and the predictor model are not updated in this way. They will be updated on Zenodo when new versions are available and they can be obtained in the VM by following Step 4 in Option 2.
-
-9. Go to the shared folder (create a subfolder if needed) and run:
+7. Go to the shared folder (create a subfolder if needed) and run:
 
    `inspired`
 
@@ -87,25 +87,33 @@ Note: The VM desktop resolution can be changed at "Preferences->LXQt Settings->M
 
 
 ### Option 2
-1. Install [Anaconda](https://docs.anaconda.com/free/anaconda/install/linux/) or [Miniconda](https://docs.anaconda.com/free/miniconda/miniconda-install/) for Linux if it is not already installed. If you are unsure which one to choose, check [here](https://docs.anaconda.com/free/distro-or-miniconda/). Note that for the purpose of running INSPIRED, either one will work. 
-
-2. With conda initiated, run the following commands:
-
-    `conda create -n inspired python=3.9`
-
-    `conda activate inspired`
+1. Install [Anaconda](https://docs.anaconda.com/free/anaconda/install/linux/) or [Miniconda](https://docs.anaconda.com/free/miniconda/miniconda-install/) for Linux if it is not already installed.  
 
-4. Go to a location where you would like to install the program (e.g., $HOME/software), run:
+2. Go to a location where you would like to install the program (e.g., $HOME/software), run:
 
-    `git clone https://github.com/cyqjh/inspired.git`
+    `git clone https://github.com/neutrons/inspired.git`
 
     After the download, you should see a folder named “inspired”. Go to the folder by running:
 
     `cd inspired`
 
     (Note: to get updated code in the future, you can simply run “git pull” in this folder)
 
-4. To download the latest DFT database and ML models from Zenodo and extract the files, run:
+3. With conda initiated, run the following commands in the project's root directory (inspired):
+
+    `.. code-block:: shell`
+
+    //Next, create the conda environment and activate
+
+    `conda env create`
+
+    `conda activate inspired-dev`
+
+    //Then, install inspired in editable mode
+
+    `pip install -e . --no-deps`
+
+4. To download the latest DFT database and ML models from Zenodo and extract the files, go to (create) a folder where you want to keep these files, run:
 
     `wget https://zenodo.org/records/11478889/files/dftdb.tar.gz`
 
@@ -115,18 +123,13 @@ Note: The VM desktop resolution can be changed at "Preferences->LXQt Settings->M
 
     `tar zxvf model.tar.gz`
 
-5. Determine if your computer is CPU-only or equipped with GPU/CUDA. If you are not sure, choose the CPU-only option. Run:
-
-    `cd ./install`
-
-    `bash conda_env_cpu.sh` (or `bash conda_env_gpu.sh` for GPU machines).
 
-    (Note: It may take a while for the installation to be completed. If you encounter errors, you may try running the commands in the sh file one by one to diagnose. If you encounter an error associated with missing pydantic, please run `pip install pydantic` to install.)
-
-6. If all packages are installed successfully, you may now go to a working directory of your choice and start INSPIRED by running:
+5. If all packages are installed successfully, you may now go to a working directory of your choice and start INSPIRED by running:
 
-     `inspired`
+    `inspired`
 
+   when you run the program for the first time, it may ask you to specify the paths to the DFT database and ML models. Set them to where you downloaded/extracted the files, and the main user interface should pop up.
+
 ### Package Versions
 The code related to already published work can be accessed (v0.2.0):
 git clone -b v0.2.0 https://github.com/neutrons/inspired.git
@@ -151,8 +154,7 @@ If you have any questions, please contact YQ Cheng at chengy@ornl.gov for help.
 
 ## Citation:
 
-Bowen Han, Andrei T. Savici, Mingda Li, Yongqiang Cheng, INSPIRED: Inelastic Neutron Scattering Prediction for Instantaneous Results and Experimental Design, Computer Physics Communications, in press (2024)
-.
+Bowen Han, Andrei T. Savici, Mingda Li, Yongqiang Cheng, [INSPIRED: Inelastic Neutron Scattering Prediction for Instantaneous Results and Experimental Design](https://doi.org/10.1016/j.cpc.2024.109288), Computer Physics Communications, 304, 109288 (2024).
 
 
 ## References: