Merge pull request #294 from ashiklom/pkgdown

Hector documentation website with `pkgdown`

Author: bpbond

.Rbuildignore

@@ -27,3 +27,7 @@
 ^src/testing$
 ^misc$
 ^data-raw$
+
+# pkgdown config and output
+^inst/_pkgdown.yml
+^docs/

.gitignore

@@ -64,3 +64,9 @@ R/batchrunner/*.csv
 .RData
 inst/doc
 vignettes/rsconnect
+
+# pkgdown output
+/docs/
+
+# vignette caches
+/vignettes/*_cache

.travis.yml

@@ -79,3 +79,12 @@ matrix:
           sources: 
             - boost-latest
       cache: packages
+
+      # Automatically deploy Hector documentation on the gh-pages
+      # branch. This is based on this guide from `pkgdown`:
+      # https://pkgdown.r-lib.org/reference/deploy_site_github.html
+      before_deploy: Rscript -e 'remotes::install_cran("pkgdown")'
+      deploy:
+        provider: script
+        script: Rscript -e 'pkgdown::deploy_site_github()'
+        skip_cleanup: true

inst/_pkgdown.yml

@@ -0,0 +1,27 @@
+navbar:
+  structure:
+    left:
+      - home
+      - manual
+      - vignettes
+      - reference
+      - news
+    right: github
+  components:
+    home:
+      icon: fa-home fa-lg
+      href: index.html
+    reference:
+      text: Reference
+      href: reference/index.html
+    manual:
+      text: Manual
+      href: articles/manual/index.html
+    vignettes:
+      text: Vignettes
+      menu:
+        - text: "A tour of the Hector R interface"
+          href: articles/intro-to-hector.html
+        - text: "Example: Using Hector to solve for an emissions pathway"
+          href: articles/hector_apply.html
+    articles: ~

vignettes/intro-to-hector.Rmd

@@ -9,6 +9,10 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(cache = TRUE)
+```
+
 This vignette provides a basic introduction for running Hector with R.
 First, it shows how to do a simple Hector run with one of Hector's built-in scenarios.
 Then, it shows how to modify Hector parameters from within R and uses this functionality to perform a simple sensitivity analysis of how the CO$_2$ fertilization parameter $\beta$ affects several Hector output variables.

vignettes/manual/AddNewComponent.Rmd

@@ -0,0 +1,90 @@
+---
+title: Adding a new component
+---
+Here are the steps to create a new component `X`.
+
+Step one:
+-----------
+
+Add two new files:  
+* headers/core/X.hpp
+* source/core/X.cpp
+
+It is best to copy and modify the corresponding files from an already constructed component.
+
+Step two (within X.hpp):  
+-----------
+Under `private` list the variables that are used in the component and their corresponding type. E.g. 
+* `tseries<unitval> x` to create a [time series](TSeries.html).
+* `unitval x` to declare a [value with associated units](Unitvals.html).
+* `double x` 
+
+Step three (within X.cpp):
+---------
+Make sure that you `#include X.hpp`.
+
+_In the constructor_  
+If the variable is a tseries, add all of the variables allowing for interpolation and their corresponding names
+	
+	XComponent::XComponent() {
+	    X_emissions.allowInterp( true ); 
+	    X_emissions.name = X_COMPONENT_NAME; 
+
+_In X::init_  
+Inform the core what data the component can provide (*registerCapability*) and what data the component depends on (*registerDependency*)
+
+	core->registerCapability( D_ATMOSPHERIC_X, getComponentName() );
+	core->registerDependency( D_LIFETIME_X, getComponentName() );
+
+_In X::setData_  
+Set the data that are used as inputs within this component, typically coming from the ini file.  [[For examples of tseries vs. unitvals in setData|AddTSeries]].
+
+_In X::prepareToRun_
+TODO: describe
+
+_In X::run_
+The run method contains the equations and code used in this component.  Here is where you would want a log statement, written out to the component's log.
+
+`H_LOG( logger, Logger::DEBUG ) << "Year " << runToDate << " X concentration = " << X.get( runToDate ) << std::endl;`
+
+TODO: mention spinup flag return.
+
+
+_In X::getData_  
+These are data that the component can provide to another component, or the data that is being generated within the component. [[For examples of tseries vs. unitvals in getData|AddTSeries]].
+
+_In X::shutDown_  
+TODO: describe
+
+Step four (Outside of X.cpp and X.hpp):
+----------------------------------------
+
+_In avistor.hpp_   
+       Add class XComponent under the declarations of subclasses  
+       Add `virtual void visit( XComponent*c ) {}`
+
+_In core.cpp_  
+	`#include "components/xcomponent.hpp"  `  
+       Under init add:  
+		`temp =  new XComponent();`  
+       `modelComponents[ temp-->getComponentName() ] = temp;`
+
+_In component_names.hpp_  
+	Under component names:   
+        `#define X_COMPONENT_NAME “x”`
+	
+_In component_data.hpp_     
+	define the variables within the component  
+	`#define D_ATMOSPHERIC_X      "X"`
+
+_In csv_outputstream_visitor.cpp_  
+	`#include 'components/xcomponent.hpp' ` 
+         
+	void CSVOutputStreamVisitor::visit( XComponent* c ) {
+   	if( !core->outputEnabled( c->getComponentName() ) && !in_spinup ) return;
+	STREAM_MESSAGE_DATE( csvFile, c, D_X_COMPONENT, current_date );
+	}
+
+_In csv_outputsream_visitor.hpp_  
+	under public  
+	`virtual void visit( XComponent* c);`

vignettes/manual/AddNewVariable.Rmd

@@ -0,0 +1,44 @@
+---
+title: Adding a new variable
+---
+
+Adding a new variable to a method
+using getData to obtain the information defined in the ini file
+
+In hector.ini under the corresponding component add variable
+	Ex: SN = 42000;
+
+
+In hpp file of component add variable as tseries/unitval/double/etc. 
+
+In component_data.hpp define the variables that are being added
+	Ex: #define D_ATMOSPHERIC_SO2 "SN"
+	These names do *not* have to match internal component variables but 
+	the ini definition *has to* match what appears in quotes
+
+In the component file .cpp 
+	under init, need to register the Capability
+	core->registerCapability( D_ATMOSPHERIC_SO2, getComponentName() );
+
+In cpp file of component, under getData and setData, add the new variables in before the Error message 
+NOTE: see tseries documentation for more information on getData
+
+	(getData)
+	else if( varName == D_ATMOSPHERIC_SO2 ) {
+       
+	returnval = SN;
+        
+	(setData)
+	else if( varName ==  D_ATMOSPHERIC_SO2  ) {
+           
+	H_ASSERT( data.date == Core::undefinedIndex(), "date not allowed" );
+   
+        SN.set( lexical_cast<double>( value ), U_GG );
+        }
+
+
+If this variable is called in another component.
+	For example if adding in a variable within the focing component
+        Ex: unitval SN = core->getData( D_ATMOSPHERIC_SO2, runToDate);
+
+If this variable is a unitval, the new unitval needs to appear in the unitval.hpp file.

vignettes/manual/Backend.Rmd

@@ -0,0 +1,34 @@
+---
+title: Hector R backend
+---
+
+A simple guide for reproducing the figures using R found with the Hartin et al., (2015) GMD study.  
+
+First
+-------
+We need 3 files that do not change:
+op.R, op_parser.R, and op_grapher.R  
+
+Second
+----------
+Make an experiment specific script that will process all of the Hector, CMIP5, and MAGICC data and save in a csv file.  
+
+For example:   
+Specify the input files and the scenarios  
+INFILES <- c("outputstream_rcp26.csv","outputstream_rcp45.csv","outputstream_rcp60.csv", "outputstream_rcp85.csv")
+
+SCENARIOS <-c("rcp26","rcp45","rcp60", "rcp85")  
+COMPARISON_DATA <- "/hector/output/comparison_data/GMD_2014/"
+
+Call op.R which will read in the model results and any supplementary data  
+source( "/hector/output/op.R" )	 # read in data, etc.   
+
+Save the dataframe (d) in a large csv file to be used in figures.R  
+write.table(d, file="hector_data.csv", row.names=F)
+
+Third  
+------
+Open figures_GMD2015.R and specify the location of the input file and the output directory at the top. 
+Save and source the file.  Figures will be generated along with correlation tables for each figure within the output directory. 
+
+

vignettes/manual/BuildHector.Rmd

@@ -0,0 +1,128 @@
+Installing and building - all platforms
+---------------------------------
+Hector relies on several libraries, all of which are freely available
+under a GPL or similar license. In order to build and run Hector, you
+will need to download and install these libraries on your system. These include:
+
+* *REQUIRED*: Boost. Free peer-reviewed portable C++ source libraries, available at http://www.boost.org/. 
+Hector uses only the parts of Boost that are implemented as header libraries (i.e., all of the code is 
+contained in header files that are included and compiled with the Hector source). Therefore, all you need to 
+do to set up Boost is to download and extract it. Hector requires Boost version ≥ 1_52_0.
+
+* *REQUIRED*: Gnu Scientific Library. A numerical library for C and C++, available at http://www.gnu.org/software/gsl/. You will need to download and follow the Boost README instructions. You will need to compile and install the GSL. To do this, unpack the GSL tar file in the location of your choice. Follow the setup instructions in the GSL README file. Briefly, they comprise three steps:  `./configure`, `make`, and `make install`. You will need to have root (superuser) privilege to perform the last step, unless you choose an install directory somewhere under your own home directory (see the GSL README for instructions on how to do this).  Hector has been tested with, and is currently using, GSL version 1.16.
+
+Installing and building - Mac OS X (Xcode)
+---------------------------------
+
+These directions assume a basic familiarity with Xcode and Mac OS X software installation. (If you're going to use `make` and not Xcode, see Linux directions below.)
+
+* Install [Xcode](https://developer.apple.com/xcode/downloads/) if necessary. Hector has been built and tested with Mac OS 10.8.5 ~~and 10.10 (Yosemite)~~. The project files are for Xcode 5.1.1.
+* Download and install Boost and GSL, following instructions above.
+* Download the [Hector zip file](https://github.com/JGCRI/hector/archive/master.zip) or check out the repository using Git.
+* From Xcode, open the project file in `project_files/Xcode/hector.cxodeproj`.
+* Build the project. See below if you encounter errors.
+* Change the current Scheme settings (Scheme->Edit Scheme) and add a command-line argument (*Arguments* tab, e.g. "input/hector_rcp45.ini").
+* Run!
+
+Xcode Build Settings to check/change if you encounter build errors:
+* *Architectures-Base SDK*: OS X 10.8 [or OS X version on machine] 
+* *Build Options-Compiler for C/C++/Objective-C*: Default compiler (Apple LLVM 5.1)
+* *Search Paths-Header Search Paths*: "/usr/local/include /usr/local/lib/boost_1_52_0/" [or other header directories]
+* *Search Paths-Library Search Paths*: "/usr/local/lib/" [or other library directories]
+* *LLVM-Language-C++-C++ Standard Library*: libc++ (LLVM C++ standard library with C++11 support)
+* *Linking-Other Linker Flags*: "-lgsl -lgslcblas -lm"
+* *User-Defined*: "GCC_MODEL_TUNING" defined as "G5"
+
+
+Installing and building - Windows
+---------------------------------
+* Install Visual Studio, if necessary.
+* Download and install *Boost* and *GSL*, following instructions above.
+* Download the [Hector zip file](https://github.com/JGCRI/hector/archive/master.zip) or check out the repository using Git.
+* TODO
+
+Installing and building - Linux
+---------------------------------
+The Hector makefiles look for the required libraries (above) in certain default
+locations, but those defaults can be overridden by setting the
+environment variables described below.
+
+**Boost**
+
+Environment variables:
+
+* BOOSTROOT (default `$(HOME)/src/boost_$(BOOSTVERSION)`).
+This variable should contain the full name of the directory created
+when you unpacked Boost. If you unpacked Boost in `$(HOME)/src`, then
+all you need to do is set the `BOOSTVERSION` variable (*q.v.* below) and leave this variable
+at its default value. If you unpacked Boost somewhere else, or if you changed the name
+of the directory that was created when you unpacked it, then you will
+need to set this variable explicitly. 
+
+* BOOSTVERSION (default: `1_52_0`). This variable should contain the
+version number of the version of Boost that you installed.  The
+version number will appear in the name of the tar file you
+downloaded. The `BOOSTVERSION` variable is used in the default value of `BOOSTROOT` to determine the default installation
+directory. If you override the default value of `BOOSTROOT` you can ignore this variable.
+
+**GNU Scientific Library (GSL)**
+
+The default
+install location for GSL is /usr/local, and that is also the default for
+Hector. Therefore, if you use the GSL default installation procedure,
+you will not need to override the Hector defaults. If you choose to
+install GSL somewhere else, use the environment variable below to indicate
+where you installed it.
+
+Environment variables:
+
+* GSLROOT (default: `/usr/local`).
+    Set this variable to the same install directory that you used when you
+    configured GSL.
+
+**Shared Library Search Path**
+
+Some of the libraries used by Hector (such as the GSL) will be
+compiled into shared libraries that will loaded at run time. It is
+best if these libraries are in directories that are part of your
+system's shared library search path. On many systems `/usr/local` is
+already in that path. If you install the libraries somewhere else,
+you may need to add the installation directories to the list given in
+`/etc/ld.so.conf`. Whether or not you install the GSL libraries in the default location, when you compile and install them 
+you may need to refresh the library cache by running
+`ldconfig` (which generally requires root privilege), or by rebooting your system 
+(which does not).
+
+If you are unable to add your library installation directory to the
+library search path, you will need to add the installation directory
+to the environment variable `LD_LIBRARY_PATH`.  Try not to use this approach if you 
+can help it because it can cause some conflicts with other software on your system.
+Instead, ask your system administrator if ldconfig is right for you.
+
+**Building Hector**
+
+Once the necessary libraries are installed, change to the top-level
+Hector directory and type `make hector`. The hector executable will
+be built in the `source/` subdirectory. If you ever need to rebuild,
+you can type `make clean` to clear away the executable and all of the
+intermediate files.
+
+There are two additional environment variables that you can use to
+fine-tune the build process. The `CXXEXTRA` variable is passed to the
+C++ compiler. You can use this variable to pass extra options to the
+compiler without changing the Makefile. In particular, specifying
+optimization options in `CXXEXTRA` such as -O or -O0 will override the
+default value of -O3.
+
+The `CXXPROF` variable is passed both to the compiler and the linker.
+It is intended to turn on performance profiling, which must be
+specified at both the compile and link stages of the build, so it
+generally should be either unset (for normal operation) or set to -pg
+(for profiling). Profiling slows the code down dramatically, so if you use it, be
+sure to unset `CXXPROF`, clean the build directories with `make clean`, 
+and rebuild when you are ready to go back to
+production runs.
+
+Installing and building - iOS/Android
+---------------------------------
+Not yet. ;)

vignettes/manual/ComponentAPI.Rmd

@@ -0,0 +1,28 @@
+---
+title: Hector component API
+---
+
+**Constructor**
+* Assigning time series names and interpolation settings.
+* Assigning default values.
+
+**init()**
+* Opening the log.
+* Storing pointer to the core (not available before then).
+* Registering dependencies (ditto).
+* Registering capabilities (ditto).
+
+**prepareToRun()**
+* Any initialization that depends on user-input data.
+* Any initialization that depends on model start date.
+
+**setData()**
+
+**getData()**
+
+**runSpinup()**
+
+**run()**
+
+**shutDown()**
+* Close the log.