Skip to content

Latest commit

 

History

History
133 lines (88 loc) · 5.14 KB

develop.md

File metadata and controls

133 lines (88 loc) · 5.14 KB
Raw

FEHM Developers

External Collaborators must sign a Contribution Agreement. Contribution Agreement for External Collaborators

Download FEHM for development

Download the repo, for developers, be sure to use SSH version instead of HTTPS to clone. These are provided on the main repo page under the Code button.

The FEHM code will be in src, the python test directory is in fehmpytests.

$ git clone [email protected]:lanl/FEHM.git
$ cd FEHM

If there is an error, a SSH Key may be needed, generate a key for your machine. RSA keys are no longer used, see instructions for new keys at: See GitHub Docs for SSH Key

Generate a SSH key (NOT RSA) in your .ssh directory.
ssh-keygen -t ed25519 -C "email.lanl.gov"
Copy contents of id_ed25519.pub into your SSH Keys on github (under settings).

Build FEHM

The build instructions are fairly straightforward but there are some platform dependent codes:

All files in src are used for the PC version of the build.

Linux version files are src/GFORTRAN/ inrestart.f, insptr.f, and mainrip.f. The linux Makefile points to the files in GFORTRAN so the user does not need to know about this sub directory. As developers, be aware if one of these files are changed, the file in GFORTRAN will also need to be changed.

dated.f is used to set the FEHM version headers. dated.f is used directly by Windows, the linux Makefile uses dated.template to write dated.f for the build.

Git Basics

A Git workflow follows these basic steps:

  • Make changes to files
  • Test changes by adding them to fehmpytests and running to verify compatibility
  • Add the files (‘stage’ files)
  • ‘Commit’ the staged files
  • Push the commit (containing all modified files) to the central repo

  1. Clone repo and create executable as described on main page README.

  2. Let’s say you’ve done some editing. The next step is to add your new test to fehmpytests (if not already there) and run the test suite to confirm that the code works correctly.

    To run Tests:

    • Add test files under /fehmpytests
    • Add Test Case to fehmpytests.py
    • Run test as a solo test

    Detailed information on adding tests is available at https://lanl.github.io/FEHM/fehmpytest-info/newtest

    python fehmpytests.py ../src/xfehm testcase

    Detailed testing information is available at https://lanl.github.io/FEHM/fehmpytest-info/testing

  3. If the test is sucessful and you’re ready to push your changes to the FEHM repository. Run the command

    git add file1 file2 ... fileN

    to add any files you have changed. You can also just run git add . if you want to add every changed file.

  4. Now, run the command

    git status

    This gives an overview of all tracked and untracked files. A tracked file is one that Git considers as part of the repo. Untracked files are everything else – think of *.o files, or some test data output generated by an FEHM run.

    Tracked files can be:

    • Unmodified (you haven’t made any changes to it, relative to the last commit)
    • Modified (you have edited the file since the last commit)
    • Staged (the file has been added and is ready to be committed and then pushed)

    Untracked files become tracked by using

    git add filename

  5. After verifying (with git status) that all the files you want to be pushed are properly staged, commit them using

    git commit -m "My first Git commit!"

    Then, push the files onto the GitHub repo with

    git push origin master

  6. If someone else has made edits, you will need to pull their changes to your local FEHM clone before you can push.

    git pull origin master
git push origin master

FEHMPYTESTS Development

The python scripts and test cases are located in FEHM/fehmpytests. Each directory has a test case with subsets defined in files under test_case/input/controls. By default, all tests run by fehmpytests.py are expected to succeed. Test cases under development can be run singly or with the option --full which will run all test cases, even those that fail.

This is the folder structure of FEHM/fehmpytests

[test-case]
    |
    |_[input]
    |   |_[control] (fehmn.files or *.files for each subset)
    |  
    |_[compare] (expected output files to check results)
    |  
    |_[output_sub1] [output_sub2] <= created by fehmpytests.py with fehmn.files copied from input/control

See documentation for adding new test cases at New Test or on repo at FEHM/docs/getting-started/fehmpytest-info/newtest.md It is recommended that new test cases first be confirmed by running FEHM without the python scripts, then evaluate results with expected output files in the compare directory.

To run FEHM without scripts, create a temporary test directory ie newtest/test_output. Copy ../input/fehmn.files into the test directory and run FEHM.