RUFAS.routines.field.crop.crop_management module

class RUFAS.routines.field.crop.crop_management.CropManagement(crop_data: CropData | None = None, harvest_efficiency: float = 1.0, potential_harvest_index: float | None = None, harvest_index: float | None = None, cut_biomass: float | None = None, wet_yield_collected: float = 0.0, dry_matter_yield_collected: float = 0.0, yield_residue: float = 0.0, yield_nitrogen: float | None = None, yield_phosphorus: float | None = None, residue_nitrogen: float = 0.0, residue_phosphorus: float = 0.0)

Bases: object

A class for managing crop operations based on crop data.

Parameters

crop_dataOptional[CropData], optional

The data class containing crop specifications and tracked attributes. If not provided, default CropData will be used.

harvest_efficiencyfloat, default 1.0

Efficiency of the harvest operation: the proportion of yield that will be extracted from the field (unitless; [0, 1]).

potential_harvest_indexOptional[float], default None

Potential harvest index for a given day (unitless).

harvest_indexOptional[float], default None

Harvest index for a given day; fraction of above-ground plant biomass that is harvestable economic yield (unitless).

cut_biomassOptional[float], default None

Total amount of the desired crop product (kg/ha).

wet_yield_collectedfloat, default 0.0

Amount of the desired crop product to be removed from the field (kg/ha).

dry_matter_yield_collectedfloat, default 0.0

Dry matter mass collected at harvest (kg/ha).

yield_residuefloat, default 0.0

Amount of dry matter residue created; unharvested yield (kg/ha).

yield_nitrogenOptional[float], default None

Nitrogen contained in the harvested yield (kg/ha).

yield_phosphorusOptional[float], default None

Phosphorus contained in the harvested yield (kg/ha).

residue_nitrogenfloat, default 0.0

Amount of nitrogen in the residue from this plant (kg/ha).

residue_phosphorusfloat, default 0.0

Amount of phosphorus in the residue from this plant (kg/ha).

root_distribution_param_da: float, default 145.0

Empirical root distribution parameter d_a (mm). Reference: Fan, Jianling, et al. “Root distribution by depth for temperate agricultural crops.” Field Crops

Research 189 (2016): 68-74, table 1. Note that the value has been converted to mm.

root_distribution_param_c: float, default -1.165

Empirical root distribution parameter c (unitless). Reference: Fan, Jianling, et al. “Root distribution by depth for temperate agricultural crops.” Field Crops

Research 189 (2016): 68-74, table 1.

Attributes

dataCropData

A reference to crop_data, on which crop management operations will be conducted.

harvest_efficiencyfloat

Efficiency of the harvest operation: the proportion of yield that will be extracted from the field (unitless; [0, 1]).

potential_harvest_indexOptional[float]

Potential harvest index for a given day (unitless).

harvest_indexOptional[float]

Harvest index for a given day; fraction of above-ground plant biomass that is harvestable economic yield (unitless).

cut_biomassOptional[float]

Total amount of the desired crop product (kg/ha).

wet_yield_collectedfloat

Amount of the desired crop product to be removed from the field (kg/ha).

dry_matter_yield_collectedfloat

Dry matter mass collected at harvest (kg/ha).

yield_residuefloat

Amount of dry matter residue created; unharvested yield (kg/ha).

yield_nitrogenOptional[float]

Nitrogen contained in the harvested yield (kg/ha).

yield_phosphorusOptional[float]

Phosphorus contained in the harvested yield (kg/ha).

residue_nitrogenfloat

Amount of nitrogen in the residue from this plant (kg/ha).

residue_phosphorusfloat

Amount of phosphorus in the residue from this plant (kg/ha).

root_distribution_param_da: float

Empirical root distribution parameter d_a (mm). Reference: Fan, Jianling, et al. “Root distribution by depth for temperate agricultural crops.” Field Crops

Research 189 (2016): 68-74, table 1. Note that the value has been converted to mm.

root_distribution_param_c: float

Empirical root distribution parameter c (unitless). Reference: Fan, Jianling, et al. “Root distribution by depth for temperate agricultural crops.” Field Crops

Research 189 (2016): 68-74, table 1.

Notes

This class is designed to handle various crop management operations using data provided by the CropData class. It is primarily based upon the “Crop Yield” (5:2.4) and “General Management” (6:1) sections of the SWAT model.

__init__(crop_data: CropData | None = None, harvest_efficiency: float = 1.0, potential_harvest_index: float | None = None, harvest_index: float | None = None, cut_biomass: float | None = None, wet_yield_collected: float = 0.0, dry_matter_yield_collected: float = 0.0, yield_residue: float = 0.0, yield_nitrogen: float | None = None, yield_phosphorus: float | None = None, residue_nitrogen: float = 0.0, residue_phosphorus: float = 0.0) → None

manage_harvest(harvest_op: HarvestOperation, field_name: str, field_size: float, time: RufasTime, soil_data: SoilData) → HarvestedCropStorageType | None

Executes the harvest operation passed on the crop that contains this module.

Parameters

harvest_opHarvestOperation

The operation to be executed on this crop.

field_namestr

The name of the field that contains this crop.

field_sizefloat

Size of the field that contains this crop (ha)

timeRufasTime

RufasTime instance containing the current time of the simulation.

soil_dataSoilData

The object tracking the attributes of the soil profile.

feed_managerFeedManager

Instance of the FeedManager that receives harvested crops.

Returns

HarvestedCropStorageType | None

The mass and nutrional information associated with the harvest’s yield, or None if the harvest produced no yield.

kill() → None

Kills the plant, preventing it from growing further, and converts all biomass to residue.

Notes

This operation is based on the SWAT model’s guidelines, where a kill operation converts all biomass of the plant to residue. It is typically executed after a harvest (when specified) or at the end of the growing season for annual plants.

determine_harvest_index() → None

Sets the crop’s harvest index based on various conditions.

Notes

If a custom harvest index is provided by the user (harvest index override), that value is used. Otherwise, the harvest index is calculated based on the crop’s accumulated heat fraction and the crop-specific optimal harvest index. The method also adjusts the harvest index based on the crop’s water deficiency.

References

SWAT 5:2.4, 5:3.3

cut_crop(collected_fraction: float = 0) → None

Performs a cut operation on the crop and, optionally, collects yield.

Parameters

collected_fraction: The fraction of the cut biomass that is collected. The remaining portion remains

in the field (between 0 and 1, inclusive).

References

SWAT Theoretical documentation section 5:2.4 and section 6:1.2

Raises

ValueError

If collected_fraction is not between 0 and 1.

Notes

The proportion of a crop that is cut is determined by the harvest index. A harvest index < 1 is the typical scenario and indicates that a proportion of biomass equal to the harvest index will be removed from the above-ground biomass of the plant. A harvest index > 1 will cut into below ground biomass as well.

The cut biomass is removed from the plant’s total biomass and the amount collected as yield is determined by the collected fraction. The remaining portion is left in the field. Cut operations without a harvest are conducted by setting collected_fraction = 0 (the default).

In addition to total biomass, the nutrient content for both the collected and uncollected portions are updated. If the simulation is using the internally-derived harvest index for cutting, then nutrients are determined with the crop-specific yield nutrient fractions. Otherwise, (harvest index override), the optimal nutrient values are used.

The above and below-ground biomass fractions are updated via the recalculated_biomass_distribution function.

This method is meant to be called from one of the various harvest operations.

_recalculate_biomass_distribution(roots_harvested: bool) → None

Recalculates how much biomass is stored above ground and how much is stored in the roots.

Parameters

roots_harvestedbool

Whether the roots were harvested.

Notes

SWAT does not specifically state how biomass should be redistributed after a harvest event. It has equation 5:2.4.4, but does not specify if this equation is used to calculate biomass distributions pre- or post-harvest.

If roots are not harvested, then the amount of biomass cut in the harvest operation is removed from the above ground biomass and the fraction of biomass that is below ground is recalculated directly. If roots are harvested, no biomass is left above ground and the fraction of biomass that is below ground is set to 1.0.

_get_harvested_crop(time: RufasTime, field_size: float) → HarvestedCropStorageType

Compiles the details of a harvest of this crop into a HarvestedCrop instance and passes it to the Feed Manager.

Parameters

timeRufasTime

RufasTime instance containing the current time of the simulation.

field_size: float

Size of the field from which this crop was harvested (ha).

feed_manager: FeedManager

Instance of the FeedManager which will receive the harvested crop.

Returns

HarvestedCrop

HarvestedCrop instance containing all the details of this harvest event.

Notes

It is assumed that the wet yield is recorded in kg / ha for crops, but stored in the FeedManager as kg.

_record_yield(field_name: str, field_size: float, year: int, day: int) → None

Records the mass and nutrients collected in an individual harvest and sends them to the OutputManager.

Parameters

field_namestr

Name of the field that contains this crop.

field_sizefloat

Size of the field that contains this crop (ha)

yearint

Year in which this harvest occurred.

dayint

Julian day on which this harvest occurred.

_transfer_residue(soil_data: SoilData, killed: bool) → None

Transfers residue from harvest to SoilData that tracks how that residue is degraded and assimilated into the soil.

Parameters

soil_dataSoilData

Object that tracks the attributes of the soil profile that contains this crop.

killedbool

Indicates whether the crop was killed by the harvest.

Notes

If a crop is harvested but not killed, then there is only residue added to the surface. If it is harvested and killed, then both surface and root residue is added to the soil profile. After transferring residue to the soil profile, the residue pools are reset to zero.

_distribute_residue_nutrients(soil_data: SoilData) → None

Distributes nutrients from plant residue into the soil profile.

Parameters

soil_dataSoilData

Object that tracks the attributes of the soil profile that contains this crop.

root_residue_massfloat

Dry matter mass of residue that is roots (kg / ha).

_add_yield_residue_to_layer(layer: LayerData, layer_fraction: float, crop_biomass: float, nitrogen: float, phosphorus: float) → None

Adds plant mass and nutrients left behind from a crop harvest into a soil layer.

Parameters

layerLayerData

The soil layer into which nutrients and residue are being added.

layer_fractionfloat

Fraction of residue and nutrients going into the soil layer.

crop_biomassfloat

Total crop biomass to be added into the soil profile (kg / ha).

nitrogenfloat

Total nitrogen to be added into the soil profile (kg / ha).

phosphorusfloat

Total phosphorus to be added into the soil profile (kg / ha).

_calculate_root_mass_distribution(bottom_depth: float) → float

Calculates the fraction of total root biomass that is contained within each soil layer.

Parameters

bottom_depthfloat

The bottom depth of the soil layer for which the root distribution is being calculated for (mm).

Returns

float

Fraction of root biomass that is at or above the passed soil depth (unitless).

References

[1]

Fan, Jianling, et al. “Root distribution by depth for temperate agricultural crops.” Field Crops Research 189 (2016): 68-74, equation (2).

Notes

If the bottom depth of a soil layer extends past the maximum depth of the roots, then that soil layer contains all of the crop’s root mass. If the bottom depth of the soil layer is 0 (i.e. it is the soil surface) then it will not contain any of the crop’s root mass.

static _determine_potential_harvest_index(heat_fraction: float, optimal_harvest_index: float) → float

Calculates the potential harvest index for a plant on a given day.

Parameters

heat_fractionfloat

Fraction of potential heat units accumulated to date (unitless).

optimal_harvest_indexfloat

Species-specific optimal harvest index for the plant at maturity under ideal conditions (unitless).

Returns

float

Potential harvest index for the day (unitless).

Notes

The harvest index is the ratio of grain to total shoot dry matter. This calculation takes into account the fraction of potential heat units accumulated to date and the species-specific optimal harvest index for the plant at maturity under ideal conditions.

References

SWAT documentation section 5:2.4.1

static _adjust_harvest_index(harvest_index: float, minimum_harvest_index: float, water_deficiency: float) → float

Calculates the actual harvest index for a given day, adjusted for water deficiency.

Parameters

minimum_harvest_indexfloat

Harvest index in drought conditions; minimum possible harvest index for the plant. Must be positive and unitless.

harvest_indexfloat

Potential harvest index for the day. Must be greater than minimum_harvest_index and unitless.

water_deficiencyfloat

Water deficiency factor for the plant (unitless).

Returns

float

Actual harvest index for the day, adjusted for water deficiency (unitless).

Notes

The method takes into consideration the minimum harvest index under drought conditions, the potential harvest index for the day, and the water deficiency factor of the plant. If values of minimum_harvest_index and harvest_index are input below their bounds, they are updated to equal their lower bounds.

References

SWAT 5:3.3.1

static determine_biomass_cut_from_whole_plant(biomass: float, harvest_index: float) → float

Calculates the maximum crop yield at harvest under ideal conditions, applicable when the harvest index is greater than 1.

Parameters

biomassfloat

Total plant biomass, measured in kilograms (kg).

harvest_indexfloat

Harvest index for a given day, indicating the ratio of grain to total shoot dry matter.

Returns

float

Crop yield, measured in kilograms per hectare (kg/ha).

Notes

The yield is calculated as a proportion of the above-ground biomass. This method is based on the SWAT model’s guidelines for crop yield calculation.

References

SWAT 5:2.4.3