This version of DAWN is built using CMake. For the version that requires Make only, check out the version tagged "cmake-less_version". It is strongly recommended, however, that you upgrade to the CMake-managed versions.
[Note: These instructions are biased towards the macOS operating system, because that's what I use. Your mileage may vary on other platforms.]
Clone this repository using
git clone --recurse-submodules https://github.com/gsrohde/DAWN.git
The --recurse-submodules option will initialize the biocro-lib
submodule and pull down its files into the DAWN/biocro-lib
subdirectory. If you cloned the DAWN repository without using the
--recurse-submodules option, run
git submodule update --init --recurse
to ensure the biocro-lib subdirectory gets populated.
DAWN uses CMake to manage the build and testing processes.
-
Install CMake if you do not already have a copy. See https://cmake.org/download/. Binary distributions are available for Windows, Linux, and macOS. In addition, a macOS installation is available from Homebrew.
-
If you haven't already installed it, install the Xerces-C++ XML parser. Installation instructions are at https://xerces.apache.org/xerces-c/install-3.html, but it may also be installed on many platforms using a package manager. (Homebrew calls the package
xerces-c.) -
Create a build directory and then
cdto it. The instructions that follow assume the build directory is the current directory and has the same parent directory as theDAWNroot directory. -
CD to the build directory.
-
Run cmake, specifying the source directory with the -S and the build directory with -B:
cmake -S ../DAWN -B .This configures and generates build instructions to be used in the build step.
If you wish to install the DAWN library and executable, and you wish to install to other than the standard location, use the
--install-prefixoption. For example, to install the libraries under/Users/yourname/local, runcmake -S ../DAWN -B . --install-prefix /Users/yourname/localNote that the install prefix must be an absolute path to a directory. We will discuss other available configuration options below.
-
Build the software with CMake:
cmake --build . -
Optional: Test the build by running ctest:
ctest
Some of the regression tests take a considerable amound of time to
run, and it can help to run them in parallel. This is done by using
the --parallel (or -j) option, specifying the number of jobs to
use. For example,
ctest --parallel 5
-
Optional: Install the DAWN library and executable:
cmake --install .If you set an installation prefix to install to a non-standard location such as
/Users/yourname/localduring the configuration step, consider adding the directory containing the DAWN executable (/Users/yourname/local/bin) to your path.
The executable is called runsim. In what follows, we assume that
you haven't necessarily installed this to your system. Instead, we
will run the copy created in the <build directory>/app directory by
the build step.
Start by CD-ing to the app directory with
cd app
(assuming you are in the DAWN_build directory to start with).
To see usage information, run
./runsim -h
(Note: If you installed runsim to a location in your path, you can
just run this with runsim -h.)
Several sample XML input files are provided in the directory
DAWN_build/app/sample_input. For example,
./runsim sample_input/harmonic_oscillator_system.xml
will run a simulation of a harmonic oscillator system and write the
results to standard output. To write to a file instead, use the
--out (or -o) option:
./runsim --out=harmonic_oscillator_result.xml sample_input/harmonic_oscillator_system.xml
To try this on a crop model, try using the input file sample_input/biocro-system.miscanthus.2002.xml:
./runsim --out=miscanthus_simulation_result.xml sample_input/biocro-system.miscanthus.2002.xml
Since the drivers specification tends to comprise a large amount of
data, and since it may sometimes be desirable to run a simulation
using different driver sets with everything else kept the same, an
option has been added to specify the drivers in a file separate from
the other simulation specifications. The command-line option to use
is called --drivers.
For example, the file sample_input/biocro-system.miscanthus.xml is
just like biocro-system.miscanthus.2002.xml except that the
drivers element has been replaced by a driver-placeholder element.
The driver data removed has been placed in a file called
sample_input/2002_weather.xml. Using these two files, we can get
the same result as in the last example above by calling
./runsim --out=miscanthus_simulation_result.xml --drivers=sample_input/2002_weather.xml \
sample_input/biocro-system.miscanthus.xml
With the ability to specify drivers independently of the main specification file, it is now easy to switch out one weather data set for another. For example, if we want to use weather data from 2005, we merely have to specify a different drivers file:
./runsim --out=miscanthus_simulation_result.xml --drivers=sample_input/2005_weather.xml \
sample_input/biocro-system.miscanthus.xml
(Note that if the simulation specification file does specify a set
of drivers, using the --drivers option will override whatever driver
information is in the specification file so that it is effectively
ignored. For example, using
sample_input/biocro-system.miscanthus.2002.xml in place of
sample_input/biocro-system.miscanthus.xml in the previous command so
that we have
./runsim --out=miscanthus_simulation_result.xml --drivers=sample_input/2005_weather.xml \
sample_input/biocro-system.miscanthus.2002.xml
will still use the 2005 weather data, not the 2002 data contained in
biocro-system.miscanthus.2002.xml.)
The Doxygen documentation is not generated by default. Instead, use
the docs target:
cmake --build . --target docs
To view the documentation, open a Web browser to
./doc/docs/index.html. (On many platforms, this may be done by
running open doc/docs/index.html from the build directory.)
Several CMake options are available for customizing the Doxygen documentation generated. See the configuration options section.
To see a list of the most useful user configuration options, run the CMake configuration/generation command with the -L option:
cmake -S ../DAWN -B . -L
(This assumes the build directory is the current directory and that
../DAWN is the relative path to the DAWN source directory.)
To see the help strings associated with each option, add the -H option:
cmake -S ../DAWN -B . -LH
(Adding the -A option will show advanced options, not documented here.)
To set a configuration option from the command line, use the -D
option. For example,
cmake -S ../DAWN -B . -DCMAKE_BUILD_TYPE=Debug
will set the build type to "Debug". Configuration variables may also
be set interactively if ccmake or cmake-gui are used.
Note: Some configuration options, such as those having to do with
customizing Doxygen output, are only available if other options are
turned on. The Doxygen configuration options, for example, require
CUSTOMIZE_DOXYGEN to be turned on. To ensure these options are
viewable when we use -L to list available options, we can use the
command
cmake -S ../DAWN -B . -L -DCUSTOMIZE_DOXYGEN=ON
Here is more extensive information about the various options:
-
BUILD_SHARED_LIBS (default: ON)
By default, both the BioCro and the DAWN libraries will be built as shared libraries. Turn this option off to build them as static libraries.
-
BIOCROLIB_STATIC (dependent option; default: ON)
This option is only available if BUILD_SHARED_LIBS is turned OFF.
-
DAWNLIB_STATIC (dependent option; default: ON)
This option is only available if BUILD_SHARED_LIBS is turned OFF.
These two sub-obtions are mainly useful if we want one library to be shared and the other to be static. For example, if we want to build both
libBioCro.aandlibdawn.dylib, we could use the configuration commandcmake -S <DAWN source directory> -B <build directory> -DBUILD_SHARED_LIBS=OFF -DDAWNLIB_STATIC=OFF -
-
CMAKE_BUILD_TYPE (default: Release)
Set to "Debug" to build a debug version of the software.
-
CMAKE_INSTALL_PREFIX (default: system determined; typically /usr/local on UNIX-like systems)
Set to a custom value if you don't want to or don't have permission to install to the default location. As noted above, this variable may be set using the
--install-prefixoption rather than using-DCMAKE_INSTALL_PREFIX=.... Note that the prefix must be an absolute path to a directory! -
INSTALL_BIOCRO_HEADERS (default: OFF)
Generally, everything needed to run BioCro simulations is available via the DAWN library functions. But if, for some reason, you are writing code that needs to access BioCro classes and functions directly, turn this option on.
Note that even when this option is OFF, the BioCro library itself is always installed.
-
INSTALL_GTEST (default: OFF)
If GoogleTest was not installed on your system when you did a CMake build, turning this option on will install it for you when you do a CMake install. Otherwise, this option has no effect.
Note that it is not necessary to install GoogleTest when running
ctestin the build directory; the tests will have been built using the GoogleTest library built by CMake. -
USE_LOCAL_SCHEMA_FILE (default: ON)
If this option is set to ON, both the build location of the simulation specification schema file (
simulation-specification.xsd) and the install location will be placed in the search path for finding the document schema (in that order). The first schema file found that parses correctly will be used in validating the simulation input and drivers files. -
USE_REMOTE_SCHEMA_URI (default: OFF)
If this option is set to ON, and if a suitable local schema file is not found, an attempt to use a version of the schema stored in the GitHub repository will be make. (Currently, the version used will be the latest version stored on the
developmentbranch.) -
CUSTOMIZE_DOXYGEN (default: OFF)
Turning this option on will make the following Doxygen customization options available:
-
ADD_TREEVIEW (default: ON)
This setting controls the appearance of a tree-like index in a side-panel (see https://www.doxygen.nl/manual/config.html#cfg_generate_treeview). The default ON setting remains on even when CUSTOMIZE_DOXYGEN is turned on.
Users of devices with limited horizonal screen space may want to turn treeview off. To do this, set CUSTOMIZE_DOXYGEN to ON and then ADD_TREEVIEW to OFF.
-
DOCUMENT_PRIVATE_MEMBERS (default: OFF)
By default, only public class members are documented. Turn this on to document private members as well.
-
USE_DOXYGEN_AWESOME_STYLESHEET (default: OFF)
Turning this on enables usage of the doxygen-awesome-css stylesheet from jothepro to create a more modern-looking appearance for the Doxygen documenation as recommended by Rafał Świdziński in his Modern CMake for C++. When this is turned on, the build will fetch the stylesheet from the GitHub repository and add it into the generated documention.
-
DOXYGEN_HTML_COLORSTYLE_HUE (default: 120 (green) if CUSTOMIZE_DOXYGEN is on, 220 (cyan-blue) otherwise)
This setting controls the color of the text in the generated documentation. It should be a value between 0 and 360. See https://www.doxygen.nl/manual/config.html#cfg_html_colorstyle_hue for details.
-
HTML_COLORSTYLE_SAT (default: 100)
This setting controls the purity (saturation) of the colors in the HTML Doxygen documentation output. Values may range from 0 (gray-scales only) to 255 (the most vivid colors).
-
Document_XercesC_Headers (default: OFF)
Include the XercesC header files among the files for Doxygen to document. Since these files don't include Doxygen-style comments, this option is probably mainly useful as a way to show all Xerces header files in the dependency graph of file includes and as a convenient way to browse the source code in these header files.
-
The diagnostic information provided by the app during validation of
the XML input file is usually somewhat less than ideal. Better
diagnostic information is provided by xmllint, a command-line tool
that comes with most Linux and macOS installations. For example, to
validate sample_input/biocro-system.miscanthus.2002.xml against the
schema file xml_schema/simulation_input.xsd, we can run
xmllint --noout --schema xml_schema/simulation_input.xsd sample_input/biocro-system.miscanthus.2002.xml
The formal requirements of the XML specification and drivers files are
determined by the XML Schema files located in the app/xml_schema
directory. See the many explanatory notes in those files for details.
Here we give a brief practical summary of the essentials.
In general, the simulation specification must specify details about the dynamical system being solved and about the solver being used to solve it.
Thus, the specification document will generally consist of a top-level
element called simulation-specification with child elements solver
and dynamical-system and so will have the following form:
<simulation-specification>
<solver ... />
<dynamical-system>
...
</dynamical-system>
</simulation-specification>
The solver element is optional. If omitted, a default value will be
used. In fact, if there is no solver specification,
dynamical-system may be used as the top-level element.
Coming soon!
The fastest way to create input files for various BioCro crop models
is to use the crop_models_to_xml.R script in conjunction with a
working R installation and together with the BioCro R package.
The BioCro R package comes with a pre-determined set of crop models for miscanthus (Miscanthus x giganteus) and willow (Salix spp.) (see https://biocro.github.io/BioCro-documentation/latest/pkgdown/reference/crop_model_definitions.html). It also comes with several years worth of weather data that may be used as system drivers (see https://biocro.github.io/BioCro-documentation/latest/pkgdown/reference/cmi_weather_data.html).
To generate a simulation specification for one of these crops, run the script as follows:
Rscript crop_models_to_xml.R <crop name> <weather data year> <output file name>
where "crop name" is "willow" or "miscanthus_x_giganteus", the weather data year is a year between 1995 and 2020 (inclusive), and "output file name" is some suitable name of your choosing. For example,
Rscript crop_models_to_xml.R willow 2002 biocro-system.willow.2002.xml
should generate an input file for the willow crop model using weather data from 2002.
It is convenient to be able to use a crop model with weather data from
multiple years. For this reason, DAWN provides the option to draw the
drivers information from a separate file (see Using external drivers
files above). Thus, the generation script also provides the option
to put the generated weather information in a separate file by using
the -d option. For example, to make an input file for the willow
crop model, but with the 2002 weather data in a separate file, we
could alter the above run command to
Rscript crop_models_to_xml.R willow 2002 biocro-system.willow.xml -d 2002_weather.xml
Lastly, we don't always want to generate the weather data file
whenever we generate the input file for a crop model: the generation
of the weather data is by far the most time-consuming step of the
script. To skip this step, use the --no-drivers option.
For example, suppose we have just used the previous command to
generate biocro-system.willow.xml, which contains the crop model
information for willow, and 2002_weather.xml, which contains the
weather data for 2002. Suppose we now want a file containing the crop
model information for miscanthus, but we don't want to go through the
time-consuming process of regenerating the 2002 weather data file.
Then we can simply run
Rscript crop_models_to_xml.R miscanthus_x_giganteous biocro-system.miscanthus.xml --no-drivers
Here, we have left out the year parameter and have added the
--no-drivers option. This command takes almost no time to complete
its run.