Merge pull request #289 from WISDEM/develop

Release with improved installation
WISDEM · Jul 15, 2024 · f534fc9 · f534fc9
2 parents 9ec2751 + a4acee3
commit f534fc9
Show file tree

Hide file tree

Showing 152 changed files with 21,446 additions and 36,138 deletions.
diff --git a/.github/workflows/CI_WEIS.yml b/.github/workflows/CI_WEIS.yml
@@ -16,14 +16,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ["ubuntu-latest", "macOS-latest"] #, "windows-latest"]
-        python-version: ["3.9","3.10","3.11"]
+        os: ["ubuntu-latest", "macOS-13", "macOS-latest", "windows-latest"] # mac13 is intel, mac-14 arm
+        python-version: ["3.9","3.10","3.11","3.12"]
 
     steps:
-      #- name: Setup GNU Fortran
-      #  #  if: false == contains( matrix.os, 'windows')
-      #  uses: awvwgk/setup-fortran@main
-
       - uses: actions/checkout@v4
 
       - name: Install conda/mamba
@@ -39,19 +35,19 @@ jobs:
           activate-environment: test
           auto-activate-base: false
 
-      - name: Add dependencies windows specific
-        if: contains( matrix.os, 'windows')
-        run: |
-          conda install -y -c intel intel-openmp mkl
+      #- name: Add dependencies windows specific
+      #  if: contains( matrix.os, 'windows')
+      #  run: |
+      #    conda install -y -c intel intel-openmp mkl
 
       - name: Add dependencies ubuntu specific
         if: false == contains( matrix.os, 'windows')
         run: |
-          conda install -y petsc4py mpi4py openmpi
+          conda install -y petsc4py mpi4py openmpi pyoptsparse
       
       - name: Add test packages
         run: |
-          conda install -y pytest pytest-cov coveralls
+          conda install -y pytest pytest-cov coveralls 
             
       - name: Show custom environment
         run: |
@@ -61,7 +57,7 @@ jobs:
       # Install WEIS
       - name: Install WEIS
         run: |
-          pip install -e .
+          python -m pip install --no-deps -e . -v
 
       # Debugging session
       #- name: Setup tmate session
@@ -81,9 +77,9 @@ jobs:
       #      python weis_driver.py
 
       # List the collected tests for debugging purposes
-      - name: List tests
-        run: |
-          pytest --collect-only weis 
+      #- name: List tests
+      #  run: |
+      #    pytest --collect-only weis 
 
       # Run all tests within WEIS, but not computationally expensive examples
       - name: Run tests within WEIS
@@ -92,11 +88,9 @@ jobs:
       
       # Run coveralls
       - name: Run coveralls
-        if: contains( matrix.os, 'ubuntu') && contains( matrix.python-version, '3.10')
-        uses: coverallsapp/github-action@v2
-        # This also works, https://github.com/AndreMiras/coveralls-python-action
-        #uses: AndreMiras/coveralls-python-action@develop
-        #env:
-        #  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        #run: |
-        #  coveralls --service=github
+        if: contains( matrix.os, 'ubuntu') && contains( matrix.python-version, '3.11')
+        #uses: coverallsapp/github-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          coveralls --service=github
diff --git a/.github/workflows/run_exhaustive_examples.yml b/.github/workflows/run_exhaustive_examples.yml
@@ -17,7 +17,7 @@ jobs:
       fail-fast: true
       matrix:
         os: ["ubuntu-latest"] #, "macOS-latest"]
-        python-version: ["3.9","3.10", "3.11"]
+        python-version: ["3.9","3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
@@ -39,7 +39,11 @@ jobs:
       - name: Add dependencies ubuntu specific
         if: false == contains( matrix.os, 'windows')
         run: |
-          conda install -y petsc4py mpi4py openmpi
+          conda install -y petsc4py mpi4py openmpi pyoptsparse
+      
+      - name: Add test packages
+        run: |
+          conda install -y pytest pytest-cov coveralls treon 
 
       - name: Show custom environment
         run: |
@@ -53,7 +57,7 @@ jobs:
       # Install WEIS
       - name: Install WEIS
         run: |
-          pip install -e .
+          python -m pip install --no-deps -e . -v
 
       # Test walkthrough notebook
       - name: Test postprocessing notebooks

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,39 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-4.10"
+  jobs:
+    # Read the docs needs a couple packages not in the environment file
+    pre_install:
+      - conda install cmake compilers
+
+
+# Shouldn't need conda for building the docs, but it is an option
+conda:
+  environment: environment.yml
+
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+#  system_packages: true
diff --git a/README.md b/README.md
@@ -47,17 +47,18 @@ The installation instructions below use the environment name, "weis-env," but an
 1.  Setup and activate the Anaconda environment from a prompt (WSL terminal on Windows or Terminal.app on Mac)
 
         conda config --add channels conda-forge
-        conda env create --name weis-env -f https://raw.githubusercontent.com/WISDEM/WEIS/develop/environment.yml
+        conda install git
+        git clone https://github.com/WISDEM/WEIS.git
+        cd WEIS
+        git checkout branch_name                         # (Only if you want to switch branches, say "develop")
+        conda env create --name weis-env -f environment.yml
         conda activate weis-env                          # (if this does not work, try source activate weis-env)
-        conda install -y petsc4py mpi4py                 # (Mac / Linux only)   
 
 
-2. Clone the repository and install the software
+2. Add in final packages and install the software
 
-        git clone https://github.com/WISDEM/WEIS.git
-        cd WEIS
-        git checkout branch_name                         # (Only if you want to switch branches, say "develop")
-        pip install --no-deps -e . -v
+        conda install -y petsc4py mpi4py pyoptsparse     # (Mac / Linux only)
+        pip install -e .
 
 3. Instructions specific for DOE HPC system Eagle.  Before executing the setup script, do:
 
@@ -67,6 +68,8 @@ The installation instructions below use the environment name, "weis-env," but an
 
 **NOTE:** To use WEIS again after installation is complete, you will always need to activate the conda environment first with `conda activate weis-env` (or `source activate weis-env`). On Eagle, make sure to reload the necessary modules
 
+For Windows users, we recommend installing `git` and the `m264` packages in separate environments as some of the libraries appear to conflict such that WISDEM cannot be successfully built from source.  The `git` package is best installed in the `base` environment.
+
 ## Developer guide
 
 If you plan to contribute code to WEIS, please first consult the [developer guide](https://weis.readthedocs.io/en/latest/how_to_contribute_code.html).

diff --git a/docs/dlc_generator.rst b/docs/dlc_generator.rst
@@ -0,0 +1,5 @@
+DLC Generator
+-------------
+
+
+**Inputs to the DLC case generator explained**
diff --git a/docs/how_to_contribute_code.rst b/docs/how_to_contribute_code.rst
@@ -21,54 +21,30 @@ There is currently very little documentation for WEIS, so you have a lot of flex
 Do not stress too much about the outline of the information you create, simply that it exists within the repo.
 We will reorganize the documentation content at a later date.
 
-Using Git subtrees
-------------------
+Developing Python Modules Used in WEIS
+--------------------------------------
+WEIS is comprised of several modules, like WISDEM, ROSCO, and RAFT. 
+Previously, we used subtrees of each module used in WEIS.
+Now, each of these modules are installed via conda.
+You can determine which version is installed in your conda environment using::
 
-The WEIS repo contains copies of other codes created by using the :code:`git subtree` commands.
-Below are some details about how to add external codes and update them.
+  conda list | grep wisdem
 
-Adding a subtree for the first time
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+where :code:`wisdem` can be replaced with any of the modules in the :code:`environment.yml`
 
-To add an external code for the first time, using OpenFAST as an example, type:
+To make changes in WISDEM, first conda uninstall it::
 
-.. code-block:: bash
+  conda uninstall --force wisdem    # omitting the --force flag will uninstall others, like rosco.  Also, mamba is less reliable here.
 
-  $ git remote add OpenFAST https://github.com/OpenFAST/openfast
-  $ git fetch OpenFAST
-  $ git subtree add -P OpenFAST OpenFAST/dev --squash
+Clone the WISDEM repository::
 
+  git clone https://github.com/WISDEM/WISDEM.git
 
-The :code:`--squash` is important so WEIS doesn't get filled up with commits from the subtree repos.
+and follow the installation instructions of that repository, **while staying within the conda environment used to install weis.**
+Since most dependencies will already be installed for each module, you can likely simply navigate to the desired repository and::
 
-Updating a subtree
-~~~~~~~~~~~~~~~~~~
+  pip install -e .
 
-Once a subtree code exists in this repo, we can update it like this.
-This first two lines are needed only if you don't have the remote for the particular subtree yet.
-If you already have the remote, only the last line is needed.
-
-.. code-block:: bash
-
-  $ git remote add OpenFAST https://github.com/OpenFAST/openfast
-  $ git fetch OpenFAST
-  $ git subtree pull --prefix OpenFAST https://github.com/OpenFAST/openfast dev --squash --message="Updating to latest OpenFAST develop"
-
-Changes to these subtree codes **should only be made to their original repos**, *not* to this WEIS repo.
-Once those individual repos have been updated, use the previous :code:`git subtree pull` command to pull in those updates to the WEIS repo.
-Once the upstream repos have your code changes, those changes have been pulled into your branch, you can then submit a PR for WEIS.
-
-Troubleshooting subtree updates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you run into trouble using :code:`git subtree`, specifically if you see :code:`git: 'subtree' is not a git command.`, try using your system git instead of any conda-installed git.
-Specifically, try using :code:`/usr/bin/git subtree` for any subtree commands.
-If that doesn't work for you, please open an issue on this repo so we can track it.
-
-Sometimes when updating a subtree, you might get an error that contains :code:`could not rev-parse split hash`, which suggests that the subtree and the more recent branch have diverged in some way.
-To fix this, manually remove the entire folder created by the subtree command (e.g. :code:`rm -rf ROSCO`.)
-Then, follow the steps to add a repo subtree for the first time.
-By deleting then re-adding the subtree repo, you ensure that all the changes are correctly added to the WEIS repo.
 
 Testing
 -------