Simulation
In addition to setting up input files, the GeoEPIC package provides functionality for running simulations and examining outputs.
Running EPIC Simulation at a Site
To initiate an EPIC simulation, a Site object must be created, which encapsulates necessary input file references that include the crop management file (OPC), weather data file (DLY), soil file (SOL), and site file (SIT). The Site object maintains references to output files, such as the annual crop yield file (ACY), that are generated during simulation execution, as shown in Listing 8:
from geoEpic.core import Site, EPICModel
from geoEpic.io import ACY, DGN
site = Site(opc='./opc/files/umstead.OPC',
dly='./weather/NCRDU.DLY',
sol='./soil/files/umstead.SOL',
sit='./sites/umstead.SIT')
Next, initialize an EPICModel object by specifying the path to the EPIC executable file and configure it with required settings. Then, execute the simulation for the required site by passing the corresponding Site object to the run method of the model, as demonstrated in Listing 9. The GeoEPIC package provides multiple user-friendly ways to initialize and configure the EPICModel object, as described in the package documentation.
model = EPICModel('./model/EPIC1102.exe')
model.start_date = '2015-01-01'
model.duration = 5 # in years
model.output_types = ['ACY', 'DGN']
model.run(site)
model.close()
Finally, examine the outputs generated by the model run. The class interfaces provided in the io module facilitate reading output files and generating publication-quality figures by integrating with Python packages such as matplotlib, as demonstrated in Listing 10.
The first line utilizes the ACY class to retrieve year-wise yield values from the generated ACY file. The second line employs the DGN class to obtain the simulated daily Leaf Area Index (LAI) from the DGN output file.
Utilizing the Workspace Class to Manage Multiple Sites
The Workspace class is a powerful component of GeoEPIC that enables efficient management and execution of EPIC simulations across multiple sites, significantly streamlining the workflow for regional-scale agricultural modeling studies. A Workspace object is initialized by two key configuration elements: (1) a configuration file that specifies global simulation settings, and (2) a sites_info file containing metadata on individual simulation sites. An example configuration file is shown in Listing 12 and is provided in the workspace template folder along with a sample sites_info file. For optimal usage and interactive exploration of simulation results, it is recommended to utilize this functionality within a Jupyter notebook environment.
from geoEpic.core import Workspace
exp = Workspace('./config.yml')
# Clear the logs and output directory
exp.clear_logs()
exp.clear_outputs()
# Run the simulations for selected sites
exp.run()
# Experiment Name
EXPName: Kansas Yield Estimation
# Model configuration
EPICModel: ./model/EPIC1102.exe
start_date: '2014-01-01'
duration: 6 # years
output_types:
- ACY # Annual Crop data file
- DGN # Daily general output file
log_dir: ./log
output_dir: ./output
# Path to folders containing input files
weather_dir: ./weather/Daily
soil_dir: ./soil/files
site_dir: ./sites
opc_dir: ./opc/files
# Path to csv file with sites' input files info
sites_info: ./info.csv
# Select specific sites from the info file
select: Random(0.1)
# Timeout for a simulation execution in seconds.
timeout: 10
The sites_info CSV file specified in the configuration contains essential metadata for each simulation site which includes paths to site-specific input files. This file enables the Workspace to systematically manage and access input files across multiple sites. The select option in the configuration file provides flexible site filtering capabilities. For instance, select: Random(0.1) implements random sampling by selecting 10% of the available sites, while select: Range(0, 1) selects all sites. Users can attach custom routines to the Workspace object, which are automatically executed after each site’s simulation. These routines facilitate automated output processing, such as variable extraction, computational analysis, or customized data export. Implementation requires defining a function decorated with @exp.routine, as demonstrated in Listing 13.
import pandas as pd
from geoEpic.core import Workspace
from geoEpic.io import DGN, ACY
exp = Workspace('./config.yml')
exp.output_dir = None # Outputs won’t be saved
@exp.routine
def save_lai(site):
lai = DGN(site.outputs['DGN']).get_var('LAI')
lai.to_csv(f'./outputs/{site.site_id}.csv')
# Execute with save_lai routine
exp.run()
In Listing 13, the @exp.routine decorator registers the save_lai function to be executed after each site’s simulation. The function reads the LAI data from the DGN output file and saves it as a CSV file in the ./outputs directory, naming the file based on the site’s ID. Setting exp.output_dir = None ensures that the EPIC output files (ACY, DGN etc.) are not saved during the execution. This approach allows users to customize post-processing steps and automate the handling of outputs for a large number of simulations, enhancing efficiency and consistency. Additionally, the Workspace object provides @exp.logger and @exp.objective decorators, which we will explore in detail in the next section.