Core Module

core

Classes:

Name	Description
EPICModel	This class handles the setup and execution of the EPIC model executable.
Problem_Wrapper	A wrapper class that provides a simplified interface for optimization and sensitivity analysis.
PygmoProblem	A class designed to define an optimization problem for use with the PyGMO library,
Site	Represents a site (ex: agricultural field) with paths to it's corresponding EPIC input files.
Workspace	This class organises the workspace for executing simulations, saving required results.

EPICModel

This class handles the setup and execution of the EPIC model executable.

Attributes:

Name	Type	Description
base_dir	str	The base directory for model runs.
executable	str	Path to the executable model file.
output_dir	str	Directory to store model outputs.
log_dir	str	Directory to store logs.
start_date	date	The start date of the EPIC model simulation.
duration	int	The duration of the EPIC model simulation in years.
output_types	list	A list of enabled output types for the EPIC model.
model_dir	str	Directory path where the executable is located.
executable_name	str	Name of the executable file.

Methods:

Name	Description
auto_Nfertilization	Update the nitrogen settings in the EPICCONT.DAT file.
auto_irrigation	Update the irrigation settings in the EPICCONT.DAT file.
close	Release the lock on the model's directory by deleting the lock file.
from_config	Create an EPICModel instance from a configuration path.
run	Execute the model for the given site and handle output files.
set_output_types	Set the model output types and update the model's print file to enable specified outputs.
setup	Set up the model run configurations based on provided settings.

duration property writable

Get the duration of the EPIC model simulation.

Returns:

Name	Type	Description
int		The duration of the simulation in years.

output_types property writable

Get the current output types of the EPIC model.

Returns:

Name	Type	Description
list		A list of enabled output types.

start_date property writable

Get the start date of the EPIC model simulation.

Returns:

Type	Description
	datetime.date: The start date of the simulation.

auto_Nfertilization(bft0, fnp=None, fmx=None)

Update the nitrogen settings in the EPICCONT.DAT file. Only BFT0 is required. Other parameters will be updated only if they are not None.

:param file_path: Path to the EPICCONT.DAT file :param bft0: Nitrogen stress factor to trigger auto fertilization (BFT0) - required :param fnp: Fertilizer application variable (FNP) - optional :param fmx: Maximum annual N fertilizer applied for a crop (FMX) - optional

auto_irrigation(bir, efi=None, vimx=None, armn=None, armx=None)

Update the irrigation settings in the EPICCONT.DAT file. Only BIR is required. Other parameters will be updated only if they are not None.

:param file_path: Path to the EPICCONT.DAT file :param bir: Water stress factor to trigger automatic irrigation (BIR) - required :param efi: Runoff volume/Volume irrigation water applied (EFI) - optional :param vimx: Maximum annual irrigation volume (VIMX) in mm - optional :param armn: Minimum single application volume (ARMN) in mm - optional :param armx: Maximum single application volume (ARMX) in mm - optional

close()

Release the lock on the model's directory by deleting the lock file.

from_config(config_path) classmethod

Create an EPICModel instance from a configuration path.

Parameters:

Name	Type	Description	Default
config_path	str	Path to the configuration file.	required

Returns:

Name	Type	Description
EPICModel		A configured instance of the EPICModel.

run(site, verbose=False, dest=None)

Execute the model for the given site and handle output files.

Parameters:

Name	Type	Description	Default
site	Site	A site instance containing site-specific configuration.	required
dest	str	Destination directory for the run. If None, a temporary directory is used.	None

Raises:

Type	Description
Exception	If any output file is not generated or is empty.

set_output_types(output_types)

Set the model output types and update the model's print file to enable specified outputs.

Parameters:

Name	Type	Description	Default
output_types	list of str	List of output types to be enabled.	required

setup(config)

Set up the model run configurations based on provided settings.

Parameters:

Name	Type	Description	Default
config	dict	Configuration dictionary containing model settings.	required

Problem_Wrapper

A wrapper class that provides a simplified interface for optimization and sensitivity analysis.

Attributes:

Name	Type	Description
problem	PygmoProblem	The PygmoProblem instance.
pg_problem	problem	The wrapped PyGMO problem instance.
algorithm		The PyGMO algorithm instance for optimization.
population		The PyGMO population instance.
population_size	int	Size of the population for optimization.

Methods:

Name	Description
init	Initialize the optimization algorithm and population.
optimize	Run the optimization process.
sensitivity_analysis	Perform sensitivity analysis using SALib with status updates.

init(algorithm, **kwargs)

Initialize the optimization algorithm and population.

Parameters:

Name	Type	Description	Default
algorithm		PyGMO algorithm class (e.g., pg.pso_gen)	required
**kwargs		Additional keyword arguments to pass to the algorithm	{}

optimize(population_size, generations)

Run the optimization process.

Parameters:

Name	Type	Description	Default
population_size	int	Size of the population for optimization	required
generations	int	Number of generations to run	required

Returns:

Type	Description
	The evolved population after optimization

sensitivity_analysis(base_no_of_samples, method)

Perform sensitivity analysis using SALib with status updates.

Parameters: - base_no_of_samples (int): Base number of samples to generate. - method (str): Sensitivity analysis method ('sobol', 'efast', 'morris').

Returns: - dict: Results of the sensitivity analysis.

PygmoProblem

A class designed to define an optimization problem for use with the PyGMO library,

Attributes:

Name	Type	Description
workspace	Workspace	The workspace object managing the environment in which the model runs.
dfs	tuple	A tuple of DataFrame-like objects that hold constraints and parameters for the problem.
bounds	ndarray	An array of parameter bounds, each specified as (min, max).
lens	ndarray	An array of cumulative lengths that help in splitting parameters for each DataFrame.

Methods:

Name	Description
apply_solution	Apply a solution vector to update parameters in all dataframes.
fitness	Evaluate the fitness of a solution vector 'x'.
get_bounds	Get the bounds for parameters as tuples of (min, max) values for each parameter across all data frames.

current property

Retrieve the current parameter values from all data frames.

Returns:

Type	Description
	np.array: A concatenated array of current parameter values from all data frames.

var_names property

Get the variable names from all data frames.

Returns:

Name	Type	Description
list		A list of variable names concatenated from all data frames. Each data frame's var_names() method is called and the results are combined into a single list.

apply_solution(x)

Apply a solution vector to update parameters in all dataframes.

Parameters:

Name	Type	Description	Default
x	array	A solution vector containing parameter values for all data frames.	required

fitness(x)

Evaluate the fitness of a solution vector 'x'.

Parameters:

Name	Type	Description	Default
x	array	A solution vector containing parameter values for all data frames.	required

Returns:

Name	Type	Description
float		The fitness value as determined by the workspace's fitness function.

get_bounds()

Get the bounds for parameters as tuples of (min, max) values for each parameter across all data frames.

Returns:

Name	Type	Description
tuple		Two numpy arrays representing the lower and upper bounds of the parameters.

Site

Represents a site (ex: agricultural field) with paths to it's corresponding EPIC input files.

Attributes:

Name	Type	Description
opc_path	str	Path to the operational practice code file.
dly_path	str	Path to the daily weather data file.
sol_path	str	Path to the soil data file.
sit_path	str	Path to the site information file.
site_id	str	Identifier for the site, derived from the sit file name if not provided.
outputs	dict	Dictionary to store output file paths.

Methods:

Name	Description
copy	Copy or symlink site files to a destination folder.
from_config	Factory method to create a Site instance from a configuration dictionary and additional site information.
get_dly	Retrieve daily weather data from a DLY file.
get_opc	Retrieve operation schedule data from an OPC file.
get_sit	Retrieve site data from a SIT file.
get_sol	Retrieve soil data from a SOL file.

elevation property

Elevation of the site.

latitude property

Latitude of the site.

longitude property

Longitude of the site.

copy(dest_folder, use_symlink=False)

Copy or symlink site files to a destination folder.

Parameters:

Name	Type	Description	Default
dest_folder	str	Destination folder path	required
use_symlinks	bool	If True, create symbolic links instead of copying files. Defaults to False.	required

Returns:

Name	Type	Description
Site		A new Site instance pointing to the copied/linked files

from_config(config, **site_info) classmethod

Factory method to create a Site instance from a configuration dictionary and additional site information.

Parameters:

Name	Type	Description	Default
config	dict	Configuration dictionary with paths and settings.	required
**site_info	dict	Keyword arguments containing site-specific information such as 'opc', 'dly', 'soil', 'SiteID', 'lat', 'lon', and 'ele'.	{}

Returns:

Name	Type	Description
Site		An instance of the Site class configured according to the provided settings.

get_dly()

Retrieve daily weather data from a DLY file.

Returns:

Name	Type	Description
DailyWeather		An instance of the DailyWeather class containing weather data.

Raises:

Type	Description
FileNotFoundError	If the DLY file does not exist at the specified path.

get_opc()

Retrieve operation schedule data from an OPC file.

Returns:

Name	Type	Description
Operation		An instance of the Operation class containing operation schedule data.

Raises:

Type	Description
FileNotFoundError	If the OPC file does not exist at the specified path.

get_sit()

Retrieve site data from a SIT file.

Returns:

Name	Type	Description
Site		An instance of the Site class containing site data.

Raises:

Type	Description
FileNotFoundError	If the SIT file does not exist at the specified path.

get_sol()

Retrieve soil data from a SOL file.

Returns:

Name	Type	Description
Soil		An instance of the Soil class containing soil data.

Raises:

Type	Description
FileNotFoundError	If the SOL file does not exist at the specified path.

Workspace

This class organises the workspace for executing simulations, saving required results.

Attributes:

Name	Type	Description
uuid	str	Unique ID assigned to each workspace instance
config	dict	Configuration data loaded from a config file.
base_dir	str	Base directory for the workspace.
routines	dict	Dictionary to store functions as routines.
objective_function	callable	Function to be executed as the objective.
dataframes	dict	Cache for dataframes.
delete_after_use	bool	Whether to delete temporary files after use.
model	EPICModel	Instance of the EPIC model.
data_logger	DataLogger	Instance of the DataLogger for logging data.

Methods:

Name	Description
clear_logs	Clear all log files and temporary run directories.
clear_outputs	Clear all output files.
close	Explicit cleanup (use this in notebooks).
fetch_log	Retrieve the logs for a specific function.
logger	Decorator to log the results of a function.
make_problem	Create a PygmoProblem instance after validating inputs.
objective	Set the objective function to be executed after simulations.
routine	Decorator to add a function as a routine without logging or returning values.
run	Run simulations for all sites or filtered by a selection string.
run_simulation	Run simulation for a given site or site information.

clear_logs()

Clear all log files and temporary run directories.

clear_outputs()

Clear all output files.

close()

Explicit cleanup (use this in notebooks).

fetch_log(func, keep=False)

Retrieve the logs for a specific function.

Parameters:

Name	Type	Description	Default
func	str	The name of the function whose logs are to be retrieved.	required
keep	bool	If True, preserve the logs after retrieval. If False, logs are deleted after reading. Defaults to False.	False

Returns:

Type	Description
	pandas.DataFrame: DataFrame containing the logs for the specified function.

logger(func)

Decorator to log the results of a function.

Parameters:

Name	Type	Description	Default
func	callable	The function to be decorated.	required

Returns:

Name	Type	Description
callable		The decorated function that logs its output.

make_problem(*dfs)

Create a PygmoProblem instance after validating inputs.

Parameters:

Name	Type	Description	Default
*dfs		Variable number of dataframes to pass to PygmoProblem	()

Returns:

Name	Type	Description
PygmoProblem		A configured optimization problem instance

Raises:

Type	Description
ValueError	If no dataframes provided or if any dataframe lacks constraints

objective(func)

Set the objective function to be executed after simulations.

Parameters:

Name	Type	Description	Default
func	callable	The objective function to be set.	required

Returns:

Name	Type	Description
callable		The decorator function that sets the objective function.

routine(func)

Decorator to add a function as a routine without logging or returning values.

Parameters:

Name	Type	Description	Default
func	callable	The function to be decorated.	required

Returns:

Name	Type	Description
callable		The decorated function that executes without logging.

run(select_str=None, progress_bar=True)

Run simulations for all sites or filtered by a selection string.

Parameters:

Name	Type	Description	Default
select_str	str	String to filter sites. Defaults to None.	None

Returns:

Name	Type	Description
Any		The result of the objective function if set, otherwise None.

run_simulation(site_or_info)

Run simulation for a given site or site information.

Parameters:

Name	Type	Description	Default
site_or_info	Site or dict	A Site object or a dictionary containing site information.	required

Returns:

Name	Type	Description
dict		The results from the post-processing routines. Output files are saved based on the options selected