Merge branch 'idaholab:main' into package_build

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,35 @@
+--------
+Issue Description
+--------
+##### What did you expect to see happen?
+
+
+##### What did you see instead?
+
+
+##### Do you have a suggested fix for the development team?
+
+
+##### Please attach the input file(s) that generate this error.  The simpler the input, the faster we can find the issue.
+
+
+
+----------------
+For Change Control Board: Issue Review
+----------------
+This review should occur before any development is performed as a response to this issue.
+- [ ] 1. Is it tagged with a type: defect or task?
+- [ ] 2. Is it tagged with a priority: critical, normal or minor?
+- [ ] 3. If it will impact requirements or requirements tests, is it tagged with requirements?
+- [ ] 4. If it is a defect, can it cause wrong results for users? If so an email needs to be sent to the users.
+- [ ] 5. Is a rationale provided? (Such as explaining why the improvement is needed or why current code is wrong.)
+
+-------
+For Change Control Board: Issue Closure
+-------
+This review should occur when the issue is imminently going to be closed.
+- [ ] 1. If the issue is a defect, is the defect fixed?
+- [ ] 2. If the issue is a defect, is the defect tested for in the regression test system?  (If not explain why not.)
+- [ ] 3. If the issue can impact users, has an email to the users group been written (the email should specify if the defect impacts stable or master)?
+- [ ] 4. If the issue is a defect, does it impact the latest release branch? If yes, is there any issue tagged with release (create if needed)?
+- [ ] 5. If the issue is being closed without a pull request, has an explanation of why it is being closed been provided?

.github/ISSUE_TEMPLATE/defect-report.yml

@@ -0,0 +1,95 @@
+name: Defect Report
+description: Report a DEFECT you experienced using the code
+title: "[DEFECT] "
+labels: defect, priority_normal
+body:
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Thank you for the defect report
+      description: Please check the suggestions below before proceeding
+      options:
+        - label: I am using the latest version of `FORCE`.
+          required: true
+        - label: |
+            I have created a [minimum, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
+            that demonstrates the defect.
+  - type: textarea
+    id: defect-description
+    attributes:
+      label: Defect Description
+      description: A clear and concise description of what the defect is.
+    validations:
+      required: true
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Describe how to reproduce the defect.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: additional-info
+    attributes:
+      label: Screenshots and Input Files
+      description: Please attach any additional information like input files, screenshots, recordings and logs, etc.
+    validations:
+      required: false
+  - type: dropdown
+    id: which-os
+    attributes:
+      label: OS
+      description: Which OS are you using?
+      options:
+        - Linux
+        - MacOS
+        - Windows
+    validations:
+      required: true
+  - type: input
+    id: which-version
+    attributes:
+      label: OS Version
+      description: Which OS version are you using?
+      placeholder: "10.15.5"
+    validations:
+      required: false
+  - type: dropdown
+    id: which-package-manager
+    attributes:
+      label: Dependency Manager
+      description: Which Dependency Manager are you using?
+      options:
+        - PIP
+        - CONDA
+    validations:
+      required: true
+  - type: checkboxes
+    id: issue-review
+    attributes:
+      label: "For Change Control Board: Issue Review"
+      description: "This review should occur before any development is performed as a response to this issue."
+      options:
+        - label: "Is it tagged with a type: defect or task?"
+        - label: "Is it tagged with a priority: critical, normal or minor?"
+        - label: "If it will impact requirements or requirements tests, is it tagged with requirements?"
+        - label: "If it is a defect, can it cause wrong results for users? If so an email needs to be sent to the users."
+        - label: "Is a rationale provided? (Such as explaining why the improvement is needed or why current code is wrong.)"
+  - type: checkboxes
+    id: issue-closure
+    attributes:
+      label: "For Change Control Board: Issue Closure"
+      description: "This review should occur when the issue is imminently going to be closed."
+      options:
+        - label: "If the issue is a defect, is the defect fixed?"
+        - label: "If the issue is a defect, is the defect tested for in the regression test system?  (If not explain why not.)"
+        - label: "If the issue can impact users, has an email to the users group been written (the email should specify if the defect impacts stable or master)?"
+        - label: "If the issue is a defect, does it impact the latest release branch? If yes, is there any issue tagged with release (create if needed)?"
+        - label: "If the issue is being closed without a pull request, has an explanation of why it is being closed been provided?"

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,42 @@
+---
+name: Feature request
+about: Suggest a new capability or addition you would like to see
+title: "[TASK] Title here"
+labels: priority_minor, task
+assignees:
+
+
+---
+
+--------
+Issue Description
+--------
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+----------------
+For Change Control Board: Issue Review
+----------------
+This review should occur before any development is performed as a response to this issue.
+- [ ] 1. Is it tagged with a type: defect or task?
+- [ ] 2. Is it tagged with a priority: critical, normal or minor?
+- [ ] 3. If it will impact requirements or requirements tests, is it tagged with requirements?
+- [ ] 4. If it is a defect, can it cause wrong results for users? If so an email needs to be sent to the users.
+- [ ] 5. Is a rationale provided? (Such as explaining why the improvement is needed or why current code is wrong.)
+
+-------
+For Change Control Board: Issue Closure
+-------
+This review should occur when the issue is imminently going to be closed.
+- [ ] 1. If the issue is a defect, is the defect fixed?
+- [ ] 2. If the issue is a defect, is the defect tested for in the regression test system?  (If not explain why not.)
+- [ ] 3. If the issue can impact users, has an email to the users group been written (the email should specify if the defect impacts stable or master)?
+- [ ] 4. If the issue is a defect, does it impact the latest release branch? If yes, is there any issue tagged with release (create if needed)?
+- [ ] 5. If the issue is being closed without a pull request, has an explanation of why it is being closed been provided?

.github/ISSUE_TEMPLATE/under-discussion.md

@@ -0,0 +1,37 @@
+---
+name: Under Discussion
+about: This issue template is aimed to propose an item of discussion for new features
+  or similar
+title: "[UNDER-DISCUSSION] New Topic"
+labels: under-discussion
+assignees:
+
+
+---
+
+--------
+Under Discussion Topic
+--------
+
+**Summary of the topic to be discussed with the development team**
+A clear and concise description of the topic to be discusses
+
+**Describe the solution you'd like to be implemented**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+----------------
+For Change Control Board: Issue Review
+----------------
+This review should occur before any development is performed as a response to this issue.
+- [ ] 1. Is it tagged with the under_discussion type?
+- [ ] 2. If implemented, it will add a new requirement?
+- [ ] 3. Is a rationale provided? (Such as explaining why the improvement is needed )
+
+-------
+For Change Control Board: Issue Closure
+-------
+This review should occur when the issue is imminently going to be closed.
+- [ ] 1. The discussion determined the addition of a new ```task``` issue?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+--------
+Pull Request Description
+--------
+##### What issue does this change request address? (Use "#" before the issue to link it, i.e., #42.)
+
+
+##### What are the significant changes in functionality due to this change request?
+
+
+----------------
+For Change Control Board: Change Request Review
+----------------
+The following review must be completed by an authorized member of the Change Control Board.
+- [ ] 1. Review all computer code.
+- [ ] 2. Make sure the Python code and commenting standards are respected (camelBack, etc.) - See on the [wiki](https://github.com/idaholab/raven/wiki/RAVEN-Code-Standards#python) for details.
+- [ ] 3. Automated Tests should pass, including run_tests, pylint, and manual building tests.
+- [ ] 4. If significant functionality is added, there must be tests added to check this. Tests should cover all possible options.  Multiple short tests are preferred over one large test.
+- [ ] 5. If the change modifies or adds a requirement or a requirement based test case, the Change Control Board's Chair or designee also needs to approve the change.  The requirements and the requirements test shall be in sync.
+- [ ] 6. The merge request must reference an issue.  If the issue is closed, the issue close checklist shall be done.
+

.github/workflows/run_tests.yml

@@ -0,0 +1,31 @@
+name: Github FORCE run tests
+run-name: ${{ github.actor }} is testing out FORCE
+on: [push, pull_request]
+jobs:
+  Runtests-FORCE-Linux:
+    runs-on: [self-hosted, linux]
+    steps:
+      - run: echo " The job was automatically triggered by a ${{ github.event_name }} event."
+      - run: echo " This job is now running on a ${{ runner.os }} server"
+      - run: echo " The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
+      - name: Check out repository code
+        uses: actions/checkout@v3
+      - run: pwd
+      - run: WD=`(cd ../../.. && pwd)` && export RAVEN_LIBS_NAME="raven_libs_"`basename $WD` && ./initalize_tests.sh
+      - run: > # The overhead time added by checking coverage is currently about 19-23%. Reducing the frequency of coverage checks may be preferable if this increases.
+          source raven/scripts/establish_conda_env.sh --load &&
+          ./check_py_coverage.sh &&
+          COV_PCT=`coverage report --format=total` &&
+          echo "::notice title=Coverage Summary::Code coverage for this repository is now $COV_PCT%. See 'coverage_results' in Artifacts for details."
+      - name: Archive tests results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: tests_results
+          path: tests
+      - name: Archive coverage results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage_results
+          path: tests/coverage_html_report

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "raven"]
+	path = raven
+	url = https://github.com/idaholab/raven.git
+[submodule "HERON"]
+	path = HERON
+	url = https://github.com/idaholab/HERON.git

README.md

@@ -1,9 +1,28 @@
 
 ![FORCE](assets/FORCE_logo-color.png)
 
+The Framework for Optimization of ResourCes and Economics is a collection of software tools, models, and datasets acquired and developed under the Integrated Energy Systems (IES) program to enable analysis of technical and economic viability of myriad IES configurations. FORCE is the consolidating interface and data repository for all the IES toolsets ranging from macro technoeconomic analysis to transient process modeling and experimental validation for integrated energy systems.
 
-# FORCE Use Cases
+# Tools
+The FORCE framework makes use of several distinct tools to enable technical and economic system analysis of integrated energy systems. The three main tools are:
 
+![HYBRID](https://github.com/idaholab/HYBRID/blob/devel/doc/logos/HYBRID_Logo_color.png)
+
+- [HYBRID](https://github.com/idaholab/HYBRID), which includes technical models of energy systems,
+
+![ORCA](https://github.com/idaholab/ORCA/blob/main/docs/logo/ORCA_transparent.png)
+
+- [ORCA](https://github.com/idaholab/ORCA), which provides tools for the real-time optimization of integrated system control, and
+
+![HERON](https://github.com/idaholab/HERON/blob/devel/logos/HERON_logo_full.png)
+
+- [HERON](https://github.com/idaholab/HERON), for long-term system cost, portfolio sizing, and dispatch optimization.
+
+While FORCE is a framework that connects these tools, currently each tool can be used independently for different parts of the integrated energy systems technical and economic analysis.
+
+## FORCE Use Cases
+
+In addition to the tools available as part of FORCE, several existing use cases that demonstrate use of FORCE are included by way of example in this code base. These are listed in brief below:
 
 | SHORT NAME                                | DESCRIPTION                                                                                                                 | REPORT                                      |
 |:-----------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------:|:-------------------------------------------:|
@@ -15,5 +34,9 @@
 
 
 
-# Notes
-The FORCE repo should contain several IES tools. For the FORCE tests in "FORCE/tests/integrations_tests" to work, raven, TEAL, and HERON should be under FORCE. The FORCE tests depend on raven libraries which can be activated as follows: "conda activate raven_libraries"
+## Testing
+The FORCE repo should contain several IES tools. For the FORCE tests in "FORCE/tests/integrations_tests" to work, raven, TEAL, and HERON should be under FORCE. The FORCE tests depend on raven libraries which can be activated as follows: `conda activate raven_libraries`
+
+## Citing FORCE
+FORCE is included in the U.S. Department of Energy [CODE database](https://www.osti.gov/doecode/biblio/74301), which includes citation guidelines for several citation styles.
+DOI:10.11578/dc.20220511.2

check_py_coverage.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+SCRIPT_DIRNAME=`dirname $0`
+SCRIPT_DIR=`(cd $SCRIPT_DIRNAME; pwd)`
+source $SCRIPT_DIR/raven/scripts/establish_conda_env.sh --quiet --load
+RAVEN_LIBS_PATH=`conda env list | awk -v rln="$RAVEN_LIBS_NAME" '$0 ~ rln {print $NF}'`
+BUILD_DIR=${BUILD_DIR:=$RAVEN_LIBS_PATH/build}
+INSTALL_DIR=${INSTALL_DIR:=$RAVEN_LIBS_PATH}
+PYTHON_CMD=${PYTHON_CMD:=python}
+JOBS=${JOBS:=1}
+mkdir -p $BUILD_DIR
+mkdir -p $INSTALL_DIR
+DOWNLOADER='curl -C - -L -O '
+
+ORIGPYTHONPATH="$PYTHONPATH"
+
+update_python_path ()
+{
+    if ls -d $INSTALL_DIR/lib/python*
+    then
+        export PYTHONPATH=`ls -d $INSTALL_DIR/lib/python*/site-packages/`:"$ORIGPYTHONPATH"
+    fi
+}
+
+update_python_path
+PATH=$INSTALL_DIR/bin:$PATH
+
+if which coverage
+then
+    echo coverage already available, skipping building it.
+else
+    if curl http://www.energy.gov > /dev/null
+    then
+       echo Successfully got data from the internet
+    else
+       echo Could not connect to internet
+    fi
+
+    cd $BUILD_DIR
+    #SHA256=56e448f051a201c5ebbaa86a5efd0ca90d327204d8b059ab25ad0f35fbfd79f1
+    $DOWNLOADER https://files.pythonhosted.org/packages/ef/05/31553dc038667012853d0a248b57987d8d70b2d67ea885605f87bcb1baba/coverage-7.5.4.tar.gz
+    tar -xvzf coverage-7.5.4.tar.gz
+    cd coverage-7.5.4
+    (unset CC CXX; $PYTHON_CMD setup.py install --prefix=$INSTALL_DIR)
+fi
+
+update_python_path
+
+cd $SCRIPT_DIR
+
+#coverage help run
+SRC_DIR=`(cd src && pwd)`
+
+# get display var
+DISPLAY_VAR=`(echo $DISPLAY)`
+# reset it
+export DISPLAY=
+
+export COVERAGE_RCFILE="$SRC_DIR/../tests/.coveragerc" # all coverage commands should automatically reference this file now
+EXTRA="--source=$SRC_DIR --parallel-mode"
+export COVERAGE_FILE=`pwd`/.coverage
+
+coverage erase
+($SRC_DIR/../run_tests "$@" --python-command="coverage run $EXTRA " || echo run_tests done but some tests failed)
+
+#get DISPLAY BACK
+DISPLAY=$DISPLAY_VAR
+
+## Prepare data and generate the html documents
+pwd
+coverage combine
+coverage html
+