Reorganize codebase

.github/workflows/ci.yml

@@ -37,17 +37,18 @@ jobs:
 
       # remove existing test output file
       - name: Remove Niwout Output File
-        run: rm Sites/Niwot/niwot.out
+        run: rm tests/smoke/niwot.out
 
       # run single sipnet run
-      - name: Run SIPNET on Sites/Niwot/niwot
-        run: ./sipnet
+      - name: Run SIPNET on tests/smoke/niwot
+        shell: bash
+        run: ./sipnet -i tests/smoke/sipnet.in
 
       # check for correct output of Niwot run
       - name: Check if niwot.out is generated
         shell: bash
         run: |
-          if [ ! -f Sites/Niwot/niwot.out ]; then
+          if [ ! -f tests/smoke/niwot.out ]; then
             echo "::error title={No Output}::Test run for Niwot site failed to produce output"
             exit 1
           fi
@@ -56,7 +57,7 @@ jobs:
       - name: Check whether niwot.out has changed 
         shell: bash
         run: |
-          if git diff --exit-code Sites/Niwot/niwot.out; then
+          if git diff --exit-code tests/smoke/niwot.out; then
             echo "Success: Niwot.out created and has not changed"
           else
             echo "::error title={Output Changed}::The test file niwot.out has changed. This is expected to fail with some changes to SIPNET. When this happens, assess correctness and then update the reference niwot.out."

.github/workflows/cpp-linter.yaml

@@ -27,4 +27,4 @@ jobs:
         if: steps.linter.outputs.checks-failed > 0
         run: |
             echo "${{ steps.linter.outputs.checks-failed }} linter checks failed" |
-            exit 1
+

CONTRIBUTING.md

@@ -1,6 +1,13 @@
 
 ## Style Guide
 
+TODO:
+1. add some 'code of conduct' lines here, or a separate file?
+2. add info about our use of `clang-format` and `clang-tidy` once that has settled down
+3. Add section about actually contributing - that is, git cloning, PRs, etc. Pull from David's nice doc he wrote for CARB.
+    1. In fact, we might want to pull a LOT from that doc and put it here. I think it covers code of conduct, too.
+4. Move the compiling section to more mainstream docs, as that is relevant to non-contributing users
+
 ## Compiling
 
 SIPNET uses `make` to build the model and documentation. There are also miscellaneous targets for running analysis workflows:

Makefile

@@ -1,32 +1,64 @@
 CC=gcc
 LD=gcc
-AR=ar
-CFLAGS=-Wall -Werror
+AR=ar -rs
+CFLAGS=-Wall -Werror -g -I./src
 LIBLINKS=-lm
+LIB_DIR=./libs
+LDFLAGS=-L$(LIB_DIR)
 
-ESTIMATE_CFILES=sipnet.c ml-metro5.c ml-metrorun.c paramchange.c runmean.c util.c spatialParams.c namelistInput.c outputItems.c events.c
-ESTIMATE_OFILES=$(ESTIMATE_CFILES:.c=.o)
-
-SENSTEST_CFILES=sipnet.c sensTest.c paramchange.c runmean.c util.c spatialParams.c namelistInput.c outputItems.c events.c
-SENSTEST_OFILES=$(SENSTEST_CFILES:.c=.o)
+# Main executables
+COMMON_CFILES:=util.c paramchange.c namelistInput.c spatialParams.c
+COMMON_CFILES:=$(addprefix src/common/, $(COMMON_CFILES))
+COMMON_OFILES=$(COMMON_CFILES:.c=.o)
 
-SIPNET_CFILES=sipnet.c frontend.c runmean.c util.c spatialParams.c namelistInput.c outputItems.c events.c
+SIPNET_CFILES:=sipnet.c frontend.c runmean.c outputItems.c events.c
+SIPNET_CFILES:=$(addprefix src/sipnet/, $(SIPNET_CFILES))
 SIPNET_OFILES=$(SIPNET_CFILES:.c=.o)
+SIPNET_LIBS=-lsipnet_common
+
+ESTIMATE_CFILES:=ml-metro5.c ml-metrorun.c
+ESTIMATE_CFILES:=$(addprefix src/estimate/, $(ESTIMATE_CFILES))
+ESTIMATE_OFILES=$(ESTIMATE_CFILES:.c=.o)
+ESTIMATE_LIBS=-lsipnet_common -lsipnet
 
-TRANSPOSE_CFILES=transpose.c util.c
+# Utilities
+TRANSPOSE_CFILES:=transpose.c
+TRANSPOSE_CFILES:=$(addprefix src/utilities/, $(TRANSPOSE_CFILES))
 TRANSPOSE_OFILES=$(TRANSPOSE_CFILES:.c=.o)
+TRANSPOSE_LIBS=-lsipnet_common
 
-SUBSET_DATA_CFILES=subsetData.c util.c namelistInput.c
+SUBSET_DATA_CFILES:=subsetData.c
+SUBSET_DATA_CFILES:=$(addprefix src/utilities/, $(SUBSET_DATA_CFILES))
 SUBSET_DATA_OFILES=$(SUBSET_DATA_CFILES:.c=.o)
+SUBSET_DATA_LIBS=-lsipnet_common
 
-CFILES=$(sort $(ESTIMATE_CFILES) $(SENSTEST_CFILES) $(SIPNET_CFILES) $(TRANSPOSE_CFILES) $(SUBSET_DATA_CFILES))
+HISTUTIL_CFILES:=bintotxt.c txttobin.c
+HISTUTIL_CFILES:=$(addprefix src/utilities/, $(HISTUTIL_CFILES))
+HISTUTIL_OFILES=$(HISTUTIL_CFILES:.c=.o)
+HISTUTIL_LIBS=-lsipnet_common
+
+CFILES=$(sort  \
+    $(ESTIMATE_CFILES) $(SENSTEST_CFILES) $(SIPNET_CFILES) $(TRANSPOSE_CFILES) $(SUBSET_DATA_CFILES) \
+    $(HISTUTIL_CFILES) \
+    )
+
+SIPNET_LIB=libsipnet.a
+COMMON_LIB=libsipnet_common.a
 
 # Doxygen
 DOXYFILE = docs/Doxyfile
 DOXYGEN_HTML_DIR = docs/html
 DOXYGEN_LATEX_DIR = docs/latex
 
-all: estimate sipnet transpose subsetData
+# the make command, with no arguments, should not build everything in this complex
+# environment
+.DEFAULT_GOAL := sipnet
+
+# the main executables - the original 'all' target
+exec: estimate sipnet transpose subsetData
+
+# with the default set to 'sipnet', we can have all do (close to) everything
+all: exec document
 
 # Only update docs if source files or Doxyfile have changed
 document: .doxygen.stamp
@@ -36,38 +68,43 @@ document: .doxygen.stamp
 	doxygen $(DOXYFILE)
 	@touch .doxygen.stamp
 
-estimate: $(ESTIMATE_OFILES)
-	$(LD) -o estimate $(ESTIMATE_OFILES) $(LIBLINKS)
+$(COMMON_LIB): $(COMMON_OFILES)
+	$(AR) $(LIB_DIR)/$(COMMON_LIB) $(COMMON_OFILES)
+
+$(SIPNET_LIB): $(SIPNET_OFILES)
+	$(AR) $(LIB_DIR)/$(SIPNET_LIB) $(SIPNET_OFILES)
 
-#sensTest: $(SENSTEST_OFILES)
-#	$(LD) -o sensTest $(SENSTEST_OFILES) $(LIBLINKS)
+sipnet: $(SIPNET_OFILES) $(COMMON_LIB)
+	$(LD) $(LDFLAGS) -o sipnet $(SIPNET_OFILES) $(LIBLINKS) $(SIPNET_LIBS)
 
-sipnet: $(SIPNET_OFILES)
-	$(LD) -o sipnet $(SIPNET_OFILES) $(LIBLINKS)
+estimate: $(ESTIMATE_OFILES) $(COMMON_LIB) $(SIPNET_LIB)
+	$(LD) $(LDFLAGS) -o estimate $(ESTIMATE_OFILES) $(LIBLINKS) $(ESTIMATE_LIBS)
 
-transpose: $(TRANSPOSE_OFILES)
-	$(LD) -o transpose $(TRANSPOSE_OFILES) $(LIBLINKS)
+transpose: $(TRANSPOSE_OFILES) $(COMMON_LIB)
+	$(LD) $(LDFLAGS) -o transpose $(TRANSPOSE_OFILES) $(LIBLINKS) $(TRANSPOSE_LIBS)
 
-subsetData: $(SUBSET_DATA_OFILES)
-	$(LD) -o subsetData $(SUBSET_DATA_OFILES) $(LIBLINKS)
+subsetData: $(SUBSET_DATA_OFILES) $(COMMON_LIB)
+	$(LD) $(LDFLAGS) -o subsetData $(SUBSET_DATA_OFILES) $(LIBLINKS) $(SUBSET_DATA_LIBS)
+
+histutil: $(HISTUTIL_OFILES) $(COMMON_LIB)
+	$(LD) $(LDFLAGS) -o bintotxt src/common/bintotxt.o $(HISTUTIL_LIBS)
+	$(LD) $(LDFLAGS) -o txttobin src/common/txttobin.o $(HISTUTIL_LIBS)
 
 clean:
-	rm -f $(ESTIMATE_OFILES) $(SIPNET_OFILES) $(TRANSPOSE_OFILES) $(SUBSET_DATA_OFILES) estimate sensTest  sipnet transpose subsetData
+	rm -f $(ESTIMATE_OFILES) $(SIPNET_OFILES) $(TRANSPOSE_OFILES) $(SUBSET_DATA_OFILES) $(COMMON_OFILES)
+	rm -f $(HISTUTIL_OFILES) $(LIB_DIR)/$(COMMON_LIB) $(LIB_DIR)/$(SIPNET_LIB)
+	rm -f estimate sensTest sipnet transpose subsetData bintotxt txttobin
 	rm -rf $(DOXYGEN_HTML_DIR) $(DOXYGEN_LATEX_DIR)
 
 # UNIT TESTS
 SIPNET_TEST_DIRS:=$(shell find tests/sipnet -type d -mindepth 1 -maxdepth 1)
 SIPNET_TEST_DIRS_RUN:= $(addsuffix .run, $(SIPNET_TEST_DIRS))
 SIPNET_TEST_DIRS_CLEAN:= $(addsuffix .clean, $(SIPNET_TEST_DIRS))
-SIPNET_LIB=libsipnet.a
-
-$(SIPNET_LIB): $(SIPNET_LIB)($(SIPNET_OFILES))
-	ranlib $(SIPNET_LIB)
 
-test: $(SIPNET_TEST_DIRS) $(SIPNET_LIB)
+test: $(SIPNET_TEST_DIRS) $(COMMON_LIB) $(SIPNET_LIB)
 
 # The dash in the build command tells make to continue if there are errors, allowing cleanup
-$(SIPNET_TEST_DIRS): $(SIPNET_LIB)
+$(SIPNET_TEST_DIRS): $(SIPNET_LIB) $(COMMON_LIB)
 	-$(MAKE) -C $@
 
 testrun: $(SIPNET_TEST_DIRS_RUN)
@@ -76,28 +113,38 @@ $(SIPNET_TEST_DIRS_RUN):
 	$(MAKE) -C $(basename $@) run
 
 testclean: $(SIPNET_TEST_DIRS_CLEAN)
-	rm -f $(SIPNET_LIB)
+#	rm -f $(SIPNET_LIB)
 
 $(SIPNET_TEST_DIRS_CLEAN):
 	$(MAKE) -C $(basename $@) clean
 
-.PHONY: all clean document estimate sipnet transpose subsetData doxygen \
-		test $(SIPNET_TEST_DIRS) $(SIPNET_LIB) testrun \
-		$(SIPNET_TEST_DIRS_RUN) testclean $(SIPNET_TEST_DIRS_CLEAN) help
+.PHONY: all clean sipnet estimate transpose subsetData histutil \
+		$(SIPNET_LIB) $(COMMON_LIB) help document .doxygen.stamp \
+		test $(SIPNET_TEST_DIRS) $(SIPNET_TEST_DIRS_RUN) testclean $(SIPNET_TEST_DIRS_CLEAN) testrun
 
 help:
-	@echo "Available targets:"
-	@echo "  help        - Display this help message."
-	@echo "  === core targets ==="
-	@echo "  all         - Builds all components."
-	@echo "  document    - Generate documentation."
-	@echo "  sipnet      - Builds the 'sipnet' executable."
-	@echo "  clean       - Removes compiled files, executables, and documentation."
-	@echo "  depend      - Automatically generates dependency information for source files."
-	@echo "  === additional tools ==="
-	@echo "  estimate    - Builds 'estimate' executable to estimate parameters using MCMC."
-	@echo "  transpose   - Builds 'transpose' executable to read in and transpose a matrix"
-	@echo "  subsetData  - Builds 'subsetData' executable that subsets input files (e.g., .clim, .dat, .valid, .sigma, .spd) from a specified start date and length of time in days."
+	@echo "Available make targets:"
+	@echo "  help         - Display this help message."
+	@echo "  === Core Targets ==="
+	@echo "  sipnet       - (also default target) Build the sipnet executable; see sipnet.in in the src/sipnet"
+	@echo "                 directory for a sample input file"
+	@echo "  estimate     - Build the estimate executable (estimates parameters using MCMC); see estimate.in in the "
+	@echo "                 src/estimate directory for sample input file"
+	@echo "  exec         - Build the above executables and all utilities (see below)"
+	@echo "  document     - Generate documentation (via doxygen)"
+	@echo "  all          - Build all above executables and the documentation"
+	@echo "  clean        - Remove compiled files, executables, and documentation"
+	@echo "  depend       - Generate build dependency information for source files and append to Makefile"
+	@echo "  === Utilities ==="
+	@echo "  transpose    - read in and transpose a matrix"
+	@echo "  subsetData   - subset input files (e.g., .clim, .dat, .valid, .sigma, .spd) from a specified start date"
+	@echo "                 and length of time in days (see src/utilities/subset.in for sample input file)"
+	@echo "  histutil     - Build bintotxt and txttobin, utilities to convert the hist file output from an estimate"
+	@echo "                 run from a binary file to a text file, and back again"
+	@echo "  === Tests ==="
+	@echo "  test         - Build the unit tests"
+	@echo "  testrun      - Run the unit tests"
+	@echo "  testclean    - Clean build artifacts and executables from the unit tests"
 
 depend::
 	makedepend $(CFILES)

README.md

@@ -0,0 +1,47 @@
+# SIPNET
+
+
+
+SIPNET (Simplified Photosynthesis and Evapotranspiration Model) is an ecosystem model designed to efficiently simulate carbon and water dynamics. Originally developed for assimilation of eddy covariance flux data in forest ecosystems, current development is focused on representing carbon balance and GHG fluxes and agricultural management practices.
+
+## Getting Started
+
+### Installing
+
+[What's required?]
+
+[Python may be required in the future, depending on what happens with formatting pre-commit hooks; we'll see]
+
+[Steps for building the program with make; mention 'make help' here too]
+
+[Add reference here to src/README.md for other utilities in this package]
+
+### Executing the Program
+
+[Running the program - example]
+
+[Description of sipnet.in and different modes, some variation of the below paragraph]
+
+The program used for forward runs of the model. Its operation is
+controlled by the file 'sipnet.in'. SIPNET can run in three different
+modes: 'standard', for a standard forward run; 'senstest', for
+performing a sensitivity test on a single parameter; and 'montecarlo',
+for running the model forward using an ensemble of parameter sets. See
+'sipnet.in' for further configuration options for each of these types of
+runs.
+
+## Documentation
+
+[Describe building the doxygen documentation and what it contains]
+
+## Roadmap or Changelog section?
+
+Do we want to list upcoming work? We could link to the issues page, and/or to the changelog
+
+## Contributing
+
+See the main [Contributing](/CONTRIBUTING.md) page
+
+## License
+
+Distributed under the BSD 3-Clause license. See [LICENSE](/LICENSE) for more information.

archive/README.md

@@ -0,0 +1,28 @@
+## The Archive (or, SIPNET's Graveyard?)
+
+This ARCHIVE directory holds code, data, and documentation from prior experiments and tests.
+It is not guaranteed to run with the current system (in fact, is almost guaranteed NOT to).
+
+## Comments on Variants from Older Main README
+
+These notes below used to reside in the main README. They have been moved here almost verbatim (other than the header), and may no longer make sense.
+
+VARIANTS OF [MAIN PROGRAM EXECUTABLES]:
+
+(WJS 7-1-2007: These have not been fully tested for compatability with
+all of the changes of the last few months. In particular, options that
+require you to specify parameter indices (e.g. sensTest) may not behave
+as expected.)
+
+(MJL 02-28-2025: as WJS comments above are, but 17+ years later!)
+
+sipnetGirdle: A modified version of SIPNET. Its operation is controlled
+by command-line arguments. WJS (7-1-2007): I have not changed this
+program to stay up to date with the recent changes made to SIPNET, and
+have not tested it after making these changes. Use at your own risk!
+
+sensTestFull: sensTest as modified by John Zobitz. Its operation is
+controlled by command-line arguments. WJS (7-1-2007): I have not tested
+this program with the changes I have made over the last few months (in
+particular, the new version of spatialParams), and thus do not guarantee
+that it will work as expected. Use at your own risk!