|
1 | | -A generic template for adding a new model to PEcAn |
2 | | -========================================================================== |
| 1 | +# PEcAn.RothC |
3 | 2 |
|
4 | | -Adding a new model to PEcAn in a few easy steps: |
| 3 | +[](https://lifecycle.r-lib.org/articles/stages.html#experimental) |
| 4 | +[](https://pecanproject.r-universe.dev/PEcAn.RothC) |
5 | 5 |
|
6 | | -1. add modeltype to BETY |
7 | | -2. add a model and PFT to BETY for use with modeltype |
8 | | -3. implement 3 functions as described below |
9 | | -4. Add tests to `tests/testthat` |
10 | | -5. Update README, documentation |
11 | | -6. Update Dockerfile and model_info.json |
12 | | -7. execute pecan with new model |
13 | 6 |
|
| 7 | +PEcAn Coupler for the RothC Model |
14 | 8 |
|
15 | | -### Three Functions |
| 9 | +Work in progress. This package is following PEcAn's standard iterative process toward full model coupling: |
16 | 10 |
|
17 | | -There are 3 functions that will need to be implemented, each of these |
18 | | -functions will need to have MODEL be replaced with the actual modeltype as |
19 | | -it is defined in the BETY database. |
| 11 | +- [x] Download, compile, and test run |
| 12 | +- [x] jobs.sh existing test run |
| 13 | +- [x] write.configs existing test run |
| 14 | +- [ ] standard output (model2netcdf) |
| 15 | + * Partial: Only soil C written |
| 16 | +- [x] test run through PEcAn interface |
| 17 | +- [ ] met2model |
| 18 | + * Partial: Evaporation still hard-coded as 0 |
| 19 | +- [ ] parameters in write.configs |
| 20 | +- [ ] extend list of PFTs, priors |
| 21 | +- [ ] initial conditions |
| 22 | +- [ ] read/write restart |
| 23 | +- [ ] non-met inputs |
20 | 24 |
|
21 | | -* `write.config.MODEL.R` |
22 | 25 |
|
23 | | - This will write the configuratin file as well as the job launcher used by |
24 | | - PEcAn. There is an example of the job execution script in the template |
25 | | - folder. The configuration file can also be a template that is found based |
26 | | - on the revision number of the model. This should use the computed results |
27 | | - specified in defaults and trait.values to write a configuration file |
28 | | - based on the PFT and traits found. |
| 26 | +## Example |
29 | 27 |
|
30 | | -* `met2model.MODEL.R` |
| 28 | +See `inst/example_workflow` for a set of scripts to run multisite ensemble simulations of soil organic carbon content. TODO: consider converting to a vignette. |
31 | 29 |
|
32 | | - This will convert the standard Met CF file to the model specific file |
33 | | - format. This will allow PEcAn to create metereological files for the |
34 | | - specific site and model. This will only be called if no meterological |
35 | | - data is found for that specific site and model combination. |
36 | 30 |
|
37 | | -* `model2netcdf.MODEL.R` |
| 31 | +## Installation |
38 | 32 |
|
39 | | - This will convert the model specific output to NACP Intercomparison |
40 | | - format. After this function is finished PEcAn will use the generated |
41 | | - output and not use the model specific outputs. The outputs should be |
42 | | - named YYYY.nc |
43 | | - |
44 | | -### Dockerization |
| 33 | +You can install the development version of `PEcAn.RothC` from r-universe: |
45 | 34 |
|
46 | | -The PEcAn system is leveraging Docker to encapsulate most of the code. |
47 | | -This will make it easier to share new model with others, without them |
48 | | -having to compile the models. The goal is for people to be able to |
49 | | -launch the model in docker, and it will register with PEcAn and is |
50 | | -almost immediatly available to be used. To accomplish this you will need to modify two files. |
51 | | - |
52 | | -* `Dockerfile` |
53 | | - |
54 | | - The [Dockerfile](https://docs.docker.com/engine/reference/builder/) is |
55 | | - like the Makefile for docker. This file is split in two pieces the |
56 | | - part at the top is to actually build the binary. This is where you |
57 | | - specify all the libraries that are needed, as well as all the build |
58 | | - tools to compile your model. The second part, starting at the second |
59 | | - `FROM` line, is where you will install only the libraries needed to |
60 | | - run the binary and copy the binary from the build stage, using the |
61 | | - `COPY --from` line. |
62 | | - |
63 | | -* `model_info.json` |
64 | | - |
65 | | - The model_info.json describes the model and is used to register the |
66 | | - model with PEcAn. In the model_info.json the only fields that are |
67 | | - really required are those at the top: `name`, `type`, `version` and |
68 | | - `binary`. All other fields are optional but are good to be filled |
69 | | - out. You can leave `version` and `binary` with the special values |
70 | | - which will be updated by the Dockerfile. |
71 | | - |
72 | | -Once the image can be build it can be pushed so others can leverage |
73 | | -of the model. For PEcAn we have been using the following naming scheme |
74 | | -for the docker images: `pecan/model-<model>-<model_version>:<pecan_version>` |
75 | | -where the `model` and `model_version` are the same as those used to |
76 | | -build the model, and `pecan_version` is the version of PEcAn this |
77 | | -model is compiled for. |
78 | | - |
79 | | -### Additional Changes |
80 | | - |
81 | | -* `README.md` |
82 | | - |
83 | | -This file should contain basic background information about the model. |
84 | | -At a minimum, this should include the scientific motivation and scope, |
85 | | -name(s) of maintainer(s), links to project homepage, and a list of a few |
86 | | -key publications. |
87 | | -relevant publications. |
88 | | - |
89 | | -* `/tests/testthat/` |
90 | | - |
91 | | -Each package should have tests that cover the key functions of the package, |
92 | | -at a minimum, the three functions above. |
| 35 | +``` r |
| 36 | +options( |
| 37 | + repos = c( |
| 38 | + getOption("repos"), |
| 39 | + pecanproject = 'https://pecanproject.r-universe.dev' |
| 40 | + ) |
| 41 | +) |
| 42 | +install.packages('PEcAn.RothC') |
| 43 | +``` |
93 | 44 |
|
94 | | -* documentation |
| 45 | +Or you can install directly from GitHub with the remotes package: |
95 | 46 |
|
96 | | -Update the `NAMESPACE`, `DESCRIPTION` and `man/*.Rd` files by running |
| 47 | +``` r |
| 48 | +remotes::install_github('pecanproject/pecan', subdir = "models/RothC") |
97 | 49 |
|
98 | | -```r |
99 | | -devtools("models/<modelname>/") |
100 | | -``` |
| 50 | +If you have a local clone of the PEcAn development repository, follow the directions provided with PEcAn (in short: use `make install`). |
0 commit comments