diff --git a/docs/howto/summa_and_git_howto.md b/docs/howto/summa_and_git_howto.md index d205ae63f..3cd002b07 100644 --- a/docs/howto/summa_and_git_howto.md +++ b/docs/howto/summa_and_git_howto.md @@ -12,7 +12,7 @@ Git is a version control tool that we use to... * to distribute official and bleeding edge releases of the model source code. ## SUMMA for model users (non developers) -In general, if you plan to apply the model rather than work directly on the source code, you may just download the model from the [SUMMA GitHub page](https://github.com/UCAR/summa). Additional archived tags and releases (including all previous SUMMA versions) are available [here](https://github.com/UCAR/summa/tags). You can simply compile the code and start working. If you want to work with the code and contribute to SUMMA development, read on. +In general, if you plan to apply the model rather than work directly on the source code, you may just download the model from the [SUMMA GitHub page](https://github.com/NCAR/summa). Additional archived tags and releases (including all previous SUMMA versions) are available [here](https://github.com/NCAR/summa/tags). You can simply compile the code and start working. If you want to work with the code and contribute to SUMMA development, read on. ## SUMMA for developers If you plan on contributing to model development or would like a systematic way to incorporate updates to the SUMMA source code, we encourage you to use Git. The following sections are designed to get you started using Git and working with the SUMMA source code repository. @@ -31,7 +31,7 @@ The basics steps to get the SUMMA source code repository are as follows. This is Using Git involves a few different copies of the archive (there is more than one way to use Git -- this is how we propose you use it): -1. **Truth repo:** this is the master copy of the archive, maintained on the GitHub server at https://github.com/UCAR/summa. You will not be able to edit this or push code to it directly. We don't either, we work on our own copy of this repo and only integrate the changes into the truth repo when they have been tested and reviewed. +1. **Truth repo:** this is the master copy of the archive, maintained on the GitHub server at https://github.com/NCAR/summa. You will not be able to edit this or push code to it directly. We don't either, we work on our own copy of this repo and only integrate the changes into the truth repo when they have been tested and reviewed. 2. **Your fork of the truth repo:** this is your version of the archive, maintained on the GitHub server by you. This is generally **not** where you edit code; it is more of a transfer point between your clone (see below) and the truth repo. Git keeps track of the differences between your fork and the truth repo. To move code changes from your fork to the truth repo, you must make a "pull request" to the SUMMA truth repo. If it's decided that your code has been sufficiently tested and reviewed and that it is a useful addition to SUMMA, then the administrators of the truth repo will do the actual pull (don't worry if some of the terminology does not yet make sense at this point). @@ -43,7 +43,7 @@ One more note: In most of the following we are assuming that you will do much of #### Step 1: Fork the repo -If you do not have a github account, create one. It's free for public repos (like the SUMMA one). Once you have an account, go to the [UCAR/summa](https://github.com/UCAR/summa) page and click "Fork" in the upper right hand corner. +If you do not have a github account, create one. It's free for public repos (like the SUMMA one). Once you have an account, go to the [NCAR/summa](https://github.com/NCAR/summa) page and click "Fork" in the upper right hand corner. #### Step 2: Clone your fork @@ -84,7 +84,7 @@ then you are not in a Git repository (note that the top level directory in a Git Assign the truth repo to a remote tracking branch called `upstream`, which will allow you easily pull in changes that are made in the truth repo and keep your clone in-sync with that version. Once you get more familiar with Git, you will be able to control which updates to include: - git remote add --tracking upstream https://github.com/UCAR/summa.git + git remote add --tracking upstream https://github.com/NCAR/summa.git #### Step 4. Sync your clone with the truth repo @@ -98,7 +98,7 @@ If you have already made changes to the code, this command by itself will not ov ##### 4.b. Merge changes -Determine which branches you will need to work with. At the very least, this will include the master branch. If you are working on a hotfix or a feature branch that already exists, you will need this branch as well; the SUMMA administrator has likely given you the name of the appropriate branch to use. Alternatively, you may want to create a new branch (e.g., if you are the first person to work on a new feature or bug fix). For more information about the branches in the SUMMA archive, see the [Git workflow for SUMMA](https://github.com/UCAR/summa/blob/master/docs/howto/summa_git_workflow.md). +Determine which branches you will need to work with. At the very least, this will include the master branch. If you are working on a hotfix or a feature branch that already exists, you will need this branch as well; the SUMMA administrator has likely given you the name of the appropriate branch to use. Alternatively, you may want to create a new branch (e.g., if you are the first person to work on a new feature or bug fix). For more information about the branches in the SUMMA archive, see the [Git workflow for SUMMA](https://github.com/NCAR/summa/blob/master/docs/howto/summa_git_workflow.md). For each branch, merge any changes from the truth repo into your local version: @@ -189,7 +189,7 @@ The SUMMA administrator and other developers will review your pull request and d ### Git workflow -For us to leverage Git to its full potential, we have implemented a Git-oriented workflow. This requires developers to adhere to a few rules regarding branch names and merge requests. A full description of the workflow we use can be found [here](https://github.com/UCAR/summa/docs/summa_git_workflow.md). +For us to leverage Git to its full potential, we have implemented a Git-oriented workflow. This requires developers to adhere to a few rules regarding branch names and merge requests. A full description of the workflow we use can be found [here](https://github.com/NCAR/summa/docs/summa_git_workflow.md). diff --git a/docs/howto/summa_git_workflow.md b/docs/howto/summa_git_workflow.md index 3c97b3aba..54c557af7 100644 --- a/docs/howto/summa_git_workflow.md +++ b/docs/howto/summa_git_workflow.md @@ -2,7 +2,7 @@ > Note: This document has been conveniently adapted from the [Cookbook for working with Git and VIC](https://github.com/UW-Hydro/VIC/wiki/Git-Workflow) -The basic workflow described here follows a workflow originally outlined by Vincent Driessen. The workflow is built around the Git version control system. A basic description of the branching strategy and release management used for SUMMA is presented here. We use a central truth repository (https://github.com/UCAR/summa) that contains our main branches and the official release version of SUMMA. All active development takes place on forks and clones of this repo. +The basic workflow described here follows a workflow originally outlined by Vincent Driessen. The workflow is built around the Git version control system. A basic description of the branching strategy and release management used for SUMMA is presented here. We use a central truth repository (https://github.com/NCAR/summa) that contains our main branches and the official release version of SUMMA. All active development takes place on forks and clones of this repo. ## Main Branches @@ -57,7 +57,7 @@ You have developed a novel way to parameterize the stomatal resistance and would The process would be as follows: - * Navigate to the main [SUMMA repo](https://github.com/UCAR/summa) + * Navigate to the main [SUMMA repo](https://github.com/NCAR/summa) * Fork the repo by clicking on the 'Fork' button in the upper right corner @@ -67,7 +67,7 @@ The process would be as follows: * Add the main SUMMA repo as the upstream remote, so you can easily merge changes that are made in the main SUMMA repo into your own local repo - git add remote upstream git@github.com:UCAR/summa.git + git add remote upstream git@github.com:NCAR/summa.git * Checkout the `develop` branch diff --git a/docs/howto/summa_mac_os_x.md b/docs/howto/summa_mac_os_x.md index df6bd4c2c..3e9859490 100644 --- a/docs/howto/summa_mac_os_x.md +++ b/docs/howto/summa_mac_os_x.md @@ -51,7 +51,7 @@ In the following I will assume that you don't have a Fortran compiler or NetCDF sudo port install ncview - 1. Now obtain the SUMMA source code from the [SUMMA source code repository](https://github.com/UCAR/summa). You may just want to download the latest tagged release. Since you are not planning to contribute to the source code, there is no need to clone or fork the repository. + 1. Now obtain the SUMMA source code from the [SUMMA source code repository](https://github.com/NCAR/summa). You may just want to download the latest tagged release. Since you are not planning to contribute to the source code, there is no need to clone or fork the repository. 1. Untar or unzip the archive, then go to the `summa/build` directory. diff --git a/readme.md b/readme.md index 61d1db0e6..49a46674a 100644 --- a/readme.md +++ b/readme.md @@ -1,16 +1,16 @@ -[![Build Status](https://travis-ci.org/UCAR/summa.svg)](https://travis-ci.org/UCAR/summa) +[![Build Status](https://travis-ci.org/NCAR/summa.svg)](https://travis-ci.org/NCAR/summa) #SUMMA This is the source code repository for the **Structure for Unifying Multiple Modeling Alternatives** or **SUMMA**. More information about SUMMA, including publications, test data sets, and sample applications can be found on the [SUMMA web site](http://www.ral.ucar.edu/projects/summa) at NCAR. ##Description -SUMMA is a hydrologic modeling aproach that is built on a common set of governing equations and a common numerical solver, which together constitute the “structural core” of the model. Different modeling approaches can then be implemented within the structural core, enabling a controlled and systematic analysis of alternative modeling options, and providing insight for future model development. +SUMMA is a hydrologic modeling aproach that is built on a common set of conservation equations and a common numerical solver, which together constitute the “structural core” of the model. Different modeling approaches can then be implemented within the structural core, enabling a controlled and systematic analysis of alternative modeling options, and providing insight for future model development. The important modeling features are: - 1. The formulation of the governing model equations is cleanly separated from their numerical solution; + 1. The formulation of the conservation model equations is cleanly separated from their numerical solution; - 1. Different model representations of physical processes (in particular, different flux parameterizations) can be used within a common set of governing equations; and + 1. Different model representations of physical processes (in particular, different flux parameterizations) can be used within a common set of conservation equations; and 1. The physical processes can be organized in different spatial configurations, including model elements of different shape and connectivity (e.g., nested multi-scale grids and HRUs). @@ -43,7 +43,9 @@ We have successfully installed SUMMA on a number of Unix-like (*nix) operating s * the LAPACK — Linear Algebra PACKage library. [LAPACK](http://www.netlib.org/lapack/) provides a series of routines for linear algebra operations, including matrix solvers. How to install the library depends on your *nix variant and is not covered here. For example, on OS X you will get all the necessary LAPACK routines by installing the ATLAS software (again, this is easiest using a package manager; note that ATLAS can take many hours to build the first time when you install it). - * a copy of the SUMMA source code from [this repo](https://github.com/UCAR/summa). You have a number of options: + * The [ATLAS](http://math-atlas.sourceforge.net/) (Automatically Tuned Linear Algebra Software) library. Note that this is required on OS X using the gfortran compiler to be able to use LAPACK. It's not clear that this is used on other *nix machines. + + * a copy of the SUMMA source code from [this repo](https://github.com/NCAR/summa). You have a number of options: * If you just want to use the latest stable release of SUMMA, then simply look for the most recent tag; * If you want the latest and greatest (and potentially erroneous), download a copy of the master branch (or clone it); @@ -51,10 +53,10 @@ We have successfully installed SUMMA on a number of Unix-like (*nix) operating s Note that you will not be able to contribute to the main SUMMA repo directly. If you are seriously interested in contributing, spend a little time learning git. It will be useful anyway. For more information about working with the SUMMA code, please see the following documents: - * [SUMMA and Git](https://github.com/UCAR/summa/blob/master/docs/howto/summa_and_git_howto.md) - * [Git workflow for SUMMA](https://github.com/UCAR/summa/blob/master/docs/howto/summa_git_workflow.md) - * [Git commands](https://github.com/UCAR/summa/blob/master/docs/howto/git_howto.md) - * [SUMMA coding conventions](https://github.com/UCAR/summa/blob/master/docs/howto/summa_coding_conventions.md) + * [SUMMA and Git](https://github.com/NCAR/summa/blob/master/docs/howto/summa_and_git_howto.md) + * [Git workflow for SUMMA](https://github.com/NCAR/summa/blob/master/docs/howto/summa_git_workflow.md) + * [Git commands](https://github.com/NCAR/summa/blob/master/docs/howto/git_howto.md) + * [SUMMA coding conventions](https://github.com/NCAR/summa/blob/master/docs/howto/summa_coding_conventions.md) Once you have all the above, you can compile SUMMA using the following steps: @@ -75,9 +77,8 @@ Once you have all the above, you can compile SUMMA using the following steps: If you get this far then SUMMA is installed correctly and functional. -Continue reading [SUMMA configuration](https://github.com/UCAR/summa/blob/master/docs/howto/summa_configuration.md) to learn more about how to configure SUMMA for your application. We strongly recommend that you get the [test applications](http://ral.ucar.edu/projects/summa) to help you get started. +Continue reading [SUMMA configuration](https://github.com/NCAR/summa/blob/master/docs/howto/summa_configuration.md) to learn more about how to configure SUMMA for your application. We strongly recommend that you get the [test applications](http://ral.ucar.edu/projects/summa) to help you get started. ## License SUMMA is distributed under the GNU Public License Version 3. For details see the file `COPYING` in the SUMMA root directory or visit the [online version](http://www.gnu.org/licenses/gpl-3.0.html). -