RUFAS.routines.field.crop.non_water_uptake module

class RUFAS.routines.field.crop.non_water_uptake.NonWaterUptake(crop_data: CropData | None, nutrient_distro_param: float = 10.0, nutrient_shapes: list[float] | None = None, previous_nutrient: float | None = None, potential_nutrient_uptake: float | None = None, layer_nutrient_potentials: float | None = None, unmet_nutrient_demands: float | None = None, nutrient_requests: float | None = None, actual_nutrient_uptakes: list[float] | None = None, total_nutrient_uptake: float | None = None)

Bases: NutrientUptake

Manages non-water uptakes in crops.

Parameters

crop_dataOptional[CropData], optional

An instance of CropData containing crop specifications and attributes. Defaults to a new instance of CropData if not provided.

nutrient_distro_paramfloat, default 10.0

Nutrient uptake distribution parameter (unitless).

nutrient_shapesOptional[List[float]], default None

Shape coefficients for nutrient uptake equations (unitless).

previous_nutrient: Optional[float], default None

Nutrient in biomass on the previous day (kg/ha).

potential_nutrient_uptakeOptional[float], default None

Potential nutrient uptake under ideal conditions (kg/ha).

layer_nutrient_potentialsOptional[float], default None

Potential nutrient uptake from each soil layer (kg/ha).

unmet_nutrient_demandsOptional[float], default None

Unmet nutrient demands by overlaying soil layers (kg/ha).

nutrient_requestsOptional[float], default None

Nutrient requested from each soil layer (kg/ha).

actual_nutrient_uptakesOptional[List[float]], default None

Actual nutrient uptake from each soil layer (kg/ha).

total_nutrient_uptakeOptional[float], default None

Total nutrient uptake by the plant (kg/ha).

Attributes

nutrient_distro_paramfloat

Nutrient uptake distribution parameter (unitless).

nutrient_shapesOptional[List[float]]

Shape coefficients for nutrient uptake equations (unitless).

previous_nutrientOptional[float]

Nutrient in biomass on the previous day (kg/ha).

potential_nutrient_uptakeOptional[float]

Potential nutrient uptake under ideal conditions (kg/ha).

layer_nutrient_potentialsOptional[float]

Potential nutrient uptake from each soil layer (kg/ha).

unmet_nutrient_demandsOptional[float]

Unmet nutrient demands by overlaying soil layers (kg/ha).

nutrient_requestsOptional[float]

Nutrient requested from each soil layer (kg/ha).

actual_nutrient_uptakesOptional[List[float]]

Actual nutrient uptake from each soil layer (kg/ha).

total_nutrient_uptakeOptional[float]

Total nutrient uptake by the plant (kg/ha).

__init__(crop_data: CropData | None, nutrient_distro_param: float = 10.0, nutrient_shapes: list[float] | None = None, previous_nutrient: float | None = None, potential_nutrient_uptake: float | None = None, layer_nutrient_potentials: float | None = None, unmet_nutrient_demands: float | None = None, nutrient_requests: float | None = None, actual_nutrient_uptakes: list[float] | None = None, total_nutrient_uptake: float | None = None)

uptake_main_process(soil_data: SoilData, nutrient_name: str, soil_layer_attr: str) → None

Generic nutrient uptake routine that extracts nutrient from the soil and updates crop_data.

Parameters

soil_dataSoilData

The SoilData object that tracks soil properties and nutrient content.

nutrient_namestr

The name of the nutrient.

soil_layer_attrstr

The soil layer attribute of the nutrient.

uptake_nutrient(layer_nutrient: list[float], layer_depths: list[float]) → None

Conducts steps necessary to uptake nutrient from soil.

Parameters

layer_nutrientList[float]

Nutrients contained in each soil layer; updated in place.

layer_depthsList[float]

The lowest depth of each soil layer.

Notes

After the actual nutrient uptake is calculated for each accessible soil layer, that amount is removed from the layer_nutrient list given as input to the function.

shift_nutrient_time(nutrient: float) → None

Copies the current nutrient value to previous_nutrient (for use between time steps).

static determine_potential_nutrient_uptake(demand: float, nutrient_start: float, mature_nutrient_fraction: float, max_growth: float) → float

Calculates the potential nutrient uptake for the day.

Parameters

demandfloat

The maximum or optimal nutrient uptake of the plant on a given day (kg/ha).

nutrient_startfloat

Nutrient biomass at the end of the previous day (kg/ha).

mature_nutrient_fractionfloat

Nutrient fraction at plant maturity (unitless).

max_growthfloat

Maximum potential biomass the plant can gain on a given day (kg/ha).

Returns

float

The potential nutrient uptake for the day (kg/ha).

References

SWAT 5:2.3.5, 5:2.3.23

classmethod determine_layer_extracted_resource(requests: list[float], sources: list[float]) → list[float]

Calculates the amount of a resource actually extracted from each layer of the soil.

Parameters

requestsList[float]

Desired amount of the resource from each layer.

sourcesList[float]

The pool of available resources in each layer.

Returns

List[float]

The actual amounts of a resource extracted from the soil layers.

References

SWAT 5:2.3.8, 5:2.3.26

static _determine_extracted_resource(request: float, source: float) → float

Calculates the amount of a resource that can be drawn from a source, based on a request.

Parameters

requestfloat

Requested amount of the resource (kg/ha).

sourcefloat

Amount of the resource available at the source (kg/ha).

Returns

float

The amount of the resource to be extracted, considering the request and source availability (kg/ha).

References

SWAT 5:2.3.8, 5:2.3.26

find_deepest_accessible_soil_layer(depths: list[float]) → None

Evaluates the accessibility of layers in the soil profile by plant roots.

Parameters

depthslist[float]

The maximum depth of each soil layer.

Notes

This function determines the total number of soil layers, identifies the deepest layer accessible to the roots, and calculates the number of layers that remain inaccessible to the plant. It provides insight into how deep the plant can potentially draw nutrients and water from the soil profile.

classmethod _determine_deepest_accessible_layer(root_depth: float, layer_bounds: list[float]) → int

Determines the deepest soil layer that is accessible to roots.

Parameters

root_depthfloat

The root depth of the plant, indicating how deep the roots extend into the soil (mm).

layer_boundslist[float]

A list containing the depths (in centimeters or meters) of the lower boundaries of each soil layer.

Returns

int

An integer indicating the deepest soil layer that the roots can access. For example, a return of 1 means only the first layer is accessible (i.e., layer_bounds[:1]), and a return of 2 means the first and second layers are accessible (i.e., layer_bounds[:2]).

Raises

ValueError

Negative root depth is provided.

Notes

This method assumes that if there are no roots (root depth of 0), then none of the soil layers are accessible for nutrient uptake by the crop.

access_layers(layer_list: list[float]) → list[float]

Utility function that removes any inaccessible layers from a list.

This method filters the input list to include only the layers of the soil profile that are accessible to the plant’s roots, based on the plant’s root depth and the soil layer depths.

Parameters

layer_listlist[float]

A list containing a value for each layer of the soil profile.

Returns

List[float]

A trimmed list with an element for each soil layer that is accessible to the plant’s roots.

classmethod determine_layer_nutrient_uptake_potential(layer_bounds: list[float], total_demand: float, root_depth: float, nutrient_distribution_parameter: float) → list[float]

Calculates the potential nutrient uptake from each soil layer based on plant demand and root depth.

Parameters

layer_boundslist[float]

A list of lower boundaries for each soil layer, in ascending order (i.e., increasing depths). Each entry represents the depth to the bottom of the layer (mm).

total_demandfloat

The total nutrient demand of the plant, indicating how much nutrient the plant needs to meet its growth requirements (kg/ha).

root_depthfloat

The current depth of the plant’s roots, determining which soil layers are accessible for nutrient uptake (mm).

nutrient_distribution_parameterfloat

A parameter that influences the distribution of nutrient uptake across the accessible soil layers, affecting how uptake is allocated among the layers (unitless).

Returns

list[float]

A list of potential nutrient uptake values from each layer, with the uptake from inaccessible layers set to zero.

Raises

ValueError

If the boundaries are not in ascending order (deeper layers should follow shallower ones). If there are duplicate depths, indicating multiple soil layers at the same depth.

References

pseudocode: C.5.C.2, C.5.C.3

classmethod _determine_nutrient_uptake_to_depth(demand: float, depth: float, root_depth: float, nutrient_distribution_parameter: float) → float

Calculates the potential nutrient uptake from the soil surface to a specified depth.

Parameters

demandfloat

The current nutrient demand of the plant (kg/ha).

depthfloat

The depth (in the same units as root_depth, typically centimeters or meters) to which nutrient uptake is calculated (mm).

root_depthfloat

The current depth of the plant’s roots (mm).

nutrient_distribution_parameterfloat

The nutrient uptake distribution parameter affecting how uptake is allocated with depth.

Returns

float

The potential amount of nutrient that can be taken up from the soil surface to the specified depth (kg/ha).

References

SWAT 5:2.3.6, 5:2.3.24

static extract_nutrient_from_soil_layers(layer_nutrients: list[float], actual_nutrient_uptakes: list[float]) → None

Extracts nutrient from the soil profile by layer.

Parameters

actual_nutrient_uptakesOptional[List[float]]

Actual nutrient uptake from each soil layer (kg/ha).

layer_nutrientslist[float]

A list of nutrients (in units such as kg/ha) present in each layer of the soil profile, from which nutrients will be extracted by the plant.

Notes

The layer_nutrients list is updated in place. Actual nutrient uptake values, calculated by another method, are subtracted from the nitrate content of each corresponding soil layer.

extend_nutrient_uptakes_to_full_profile(actual_nutrient_uptakes: list[float]) → None

Determines the actual nutrient uptakes for the full soil profile, not just the accessible layers.

Parameters

actual_nutrient_uptakesOptional[List[float]]

Actual nutrient uptake from each soil layer (kg/ha).

Notes

Zeros are appended to the list of nutrient uptakes for each inaccessible soil layer, indicating no nutrient uptake from those layers.

classmethod determine_nutrient_shape_parameters(half_mature_heat_fraction: float, mature_heat_fraction: float, emergence_nutrient_fraction: float, half_mature_nutrient_fraction: float, mature_nutrient_fraction: float) → list[float]

Calculates the shape coefficients for the nutrient fraction equation.

Parameters

half_mature_heat_fractionfloat

PHU (Potential Heat Units) fraction at half-maturity.

mature_heat_fractionfloat

PHU fraction at full maturity.

emergence_nutrient_fractionfloat

Nutrient fraction at emergence.

half_mature_nutrient_fractionfloat

Nutrient fraction at half-maturity.

mature_nutrient_fractionfloat

Nutrient fraction at maturity.

Returns

List[float]

A list containing the first and second shape coefficients, respectively.

Notes

SWAT assumes that the difference between the nutrient fraction near maturity and the nutrient fraction at maturity in the crop is equal to 0.00001 (as per SWAT theoretical documentation pages 331 and 336, top paragraphs of both). Therefore, the near mature nutrient fraction is adjusted to meet that assumption in this calculation.

References

SWAT 5:2.3.2, 5:2.3.3, 5:2.3.20, 5:2.3.21

Raises

ValueError

If half_mature_heat_fraction equals mature_heat_fraction.

classmethod _determine_shape_log(heat_fraction: float, nutrient_fraction: float, mature_nutrient_fraction: float, emergence_nutrient_fraction: float) → float

Calculate the logarithmic component of the shape coefficient formulae for nutrient uptake.

Parameters

heat_fractionfloat

PHU (Potential Heat Units) fraction of interest.

nutrient_fractionfloat

Nutrient fraction of interest at a specific point in the growth cycle.

mature_nutrient_fractionfloat

Nutrient fraction at maturity, indicating the nutrient level when the plant is fully matured.

emergence_nutrient_fractionfloat

Nutrient fraction at emergence, indicating the initial nutrient level when the plant emerges.

Returns

float

The logarithmic term of the nutrient shape coefficients, crucial for calculating the shape coefficients used in nutrient uptake modeling (unitless).

Raises

ValueError

If any of the nutrient or heat fractions are outside the range of 0 to 1. If emergence_nutrient_fraction is equivalent to mature_nutrient_fraction. If nutrient_fraction is equivalent to emergence_nutrient_fraction or mature_nutrient_fraction. If nutrient_fraction is greater than or equal to emergence_nutrient_fraction. If nutrient_fraction is 0. If heat_fraction is 0. If the calculated denominator is greater than 1.

References

SWAT 5:2.3.2, 5:2.3.3, 5:2.3.20, 5:2.3.21

static determine_optimal_nutrient_fraction(heat_fraction: float, emergence_nutrient_fraction: float, mature_nutrient_fraction: float, shape1: float, shape2: float) → float

Calculates the optimal fraction of nutrient in the plant biomass on a given day.

Parameters

heat_fractionfloat

Fraction of total potential heat units (PHU fraction) accumulated to date.

emergence_nutrient_fractionfloat

Expected fraction of plant biomass comprised of nutrient at plant emergence.

mature_nutrient_fractionfloat

Nutrient fraction at maturity.

shape1float

First nutrient uptake shape parameter.

shape2float

Second nutrient uptake shape parameter.

Returns

float

The calculated optimal nutrient fraction in the plant biomass for the given day.

References

SWAT Reference: Equations 5:2.3.1, 5:2.3.19

static determine_optimal_nutrient(fraction: float, whole: float) → float

Calculate the mass of a nutrient as a constituent from the fractional mass of the whole.

Parameters

fractionfloat

Proportion of the whole made up of the nutrient (unitless).

wholefloat

Total mass of the whole in which the nutrient is a part (kg/ha).

Returns

float

Mass of the nutrient as a constituent of the whole (kg/ha).

References

SWAT 5:2.3.4, 5:2.3.22

static determine_stored_nutrient(uptake: float, previous: float, fixed: float) → float

Calculates the mass of the nutrient stored in plant material after the current day’s growth cycle.

Parameters

uptakefloat

The mass of the nutrient taken up by the plant on the current day (kg/ha).

previousfloat

The nutrient mass stored in the plant at the end of the previous day (kg/ha).

fixedfloat

The mass of nutrient fixed by the plant on the current day, applicable only to nutrient (kg/ha).

Returns

float

The total mass of the nutrient in the plant at the end of the current day (kg/ha).

classmethod determine_layer_nutrient_uptake(layer_demands: list[float], layer_uptake_potentials: list[float], layer_nutrient: list[float]) → list[float]

Calculates nutrient amount uptaken from each soil layer.

Parameters

layer_demandsList[float]

List of demands for the nutrient from each soil layer not met by the above layers.

layer_uptake_potentialsList[float]

List of maximum potential uptake of the nutrient from each soil layer.

layer_nutrientList[float]

List of nutrient amounts available in each soil layer.

Returns

List[float]

Amount of nutrient mass taken up from each soil layer.

References

SWAT 5:2.3.1, 5:2.3.2 (see paragraphs below equations 5:2.3.8 and 5:2.3.26)

_abc_impl = <_abc._abc_data object>