RUFAS.biophysical.animal.pen module

class RUFAS.biophysical.animal.pen.Pen(pen_id: int, pen_name: str, vertical_dist_to_milking_parlor: float, horizontal_dist_to_milking_parlor: float, number_of_stalls: int, housing_type: str, pen_type: str, animal_combination: AnimalCombination, max_stocking_density: float, minutes_away_for_milking: int, first_parlor_processor: str | None, parlor_stream_name: str | None, manure_streams: list[dict[str, str | float]])

Bases: object

This class represents a pen that houses animals during the simulation.

Parameters

pen_idint

Unique identifier for the pen.

pen_namestr

Name of the pen.

vertical_dist_to_milking_parlorfloat

Vertical distance from the pen to the milking parlor (m).

horizontal_dist_to_milking_parlorfloat

Horizontal distance from the pen to the milking parlor (m).

number_of_stallsint

Number of stalls available in the pen.

housing_typestr

Type of housing used in the pen.

pen_typestr

The pen type (freestall, tiestall, open lot, or bedded pack).

animal_combinationAnimalCombination

Combination of animal categories housed in the pen.

max_stocking_densityfloat

Maximum allowable stocking density for animals in the pen.

minutes_away_for_milkingint

Time required to reach the milking parlor from the pen (in minutes).

first_parlor_processorstr | None

Name of the processor to which the parlor stream will be sent.

parlor_stream_namestr | None

Name of the parlor stream.

manure_streamslist[dict[str, str | float]]

List of dictionaries containing manure stream information.

Attributes

idint

Internal identifier for the pen.

pen_namestr

Name of the pen.

vertical_dist_to_parlorfloat

Vertical distance from the pen to the milking parlor, in meters.

horizontal_dist_to_parlorfloat

Horizontal distance from the pen to the milking parlor, in meters.

num_stallsint

Total number of stalls available in the pen.

housing_typestr

Type of housing used in the pen.

pen_typestr

The pen type (freestall, tiestall, open lot, or bedded pack).

animal_combinationAnimalCombination

Combination of animal categories housed in the pen.

max_stocking_densityfloat

Maximum allowable stocking density for animals in the pen.

minutes_away_for_milkingint

Time required to reach the milking parlor from the pen (in minutes).

first_parlor_processorstr

Name of the processor to which the parlor stream will be sent.

parlor_stream_namestr | None

Name of the parlor stream.

manure_streamslist[dict[str, str | float]]

List of dictionaries containing manure stream information.

animals_in_pendict[int, Animal]

Dictionary mapping animal IDs to Animal objects housed in the pen.

rationdict[RUFAS_ID, float]

Maps RuFaS Feed ID to the amount of that feed in the ration (kg dry matter).

average_nutrition_evaluationNutritionEvaluationResults

Average surpluses and/or deficits of nutrients supplied to animals in the pen.

allocated_feedsset

Set of IDs for the feeds allocated to this pen.

omOutputManager

The output manager instance used to store and manage output data.

__init__(pen_id: int, pen_name: str, vertical_dist_to_milking_parlor: float, horizontal_dist_to_milking_parlor: float, number_of_stalls: int, housing_type: str, pen_type: str, animal_combination: AnimalCombination, max_stocking_density: float, minutes_away_for_milking: int, first_parlor_processor: str | None, parlor_stream_name: str | None, manure_streams: list[dict[str, str | float]]) → None

property current_stocking_density: float

Returns the current stocking density of the pen.

Returns

float

the current stocking density of the pen.

property is_populated: bool

Returns whether the pen is populated.

Returns

bool

True if the pen is populated, False otherwise.

property needs_ration_formulation: bool

Returns whether pen needs a ration formulated.

Returns

bool

True if pen needs ration formulation.

Notes

This is currently written to cover the case in which a ration was not formulated due to the pen being empty,

but was populated in subsequent days.

property animal_types_in_pen: set[AnimalType]

Returns a set of animal types currently in the pen.

Returns

set[AnimalType]

A set of unique animal types defined by the animal_type property of the animals in the pen.

property number_of_lactating_cows_in_pen: int

Returns the number of lactating cows in the pen.

Returns

int

The number of lactating cows present in the pen.

property cows_in_pen: list[Animal]

Returns all the cows in the current pen.

Returns

list[Animal]

A list of cows in pen.

property average_growth: float

Computes the average daily growth of all animals in the pen.

Returns

float

The average daily growth of the animals, or 0 if the pen is empty.

property total_manure_excretion: AnimalManureExcretions

Calculates the total manure excretion of all animals in the pen by summing up the individual manure excretions from the digestive systems of each animal.

Returns

AnimalManureExcretions

The total manure excretion for all animals in the pen.

property average_nutrition_requirements: NutritionRequirements

Computes the average nutritional requirements for all animals in a pen.

Returns

NutritionRequirements

The average nutritional requirements across all animals in the pen, or an empty NutritionRequirements object if the pen contains no animals.

property average_nutrition_supply: NutritionSupply

Computes the average nutritional supply for all animals in a pen.

Returns

NutritionSupply

The average nutritional supply across all animals in the pen, or an empty NutritionSupply object if the pen contains no animals.

property average_phosphorus_requirements: float

Calculates the average phosphorus requirements for all animals within the pen.

Returns

float

The computed average of phosphorus requirements for all animals in the pen, or 0 if the pen is empty.

property average_body_weight: float

Calculate the average body weight of animals in the pen.

Returns

float

Average body weight of animals in the pen (kg).

property average_milk_production: float

Calculate the average milk production for the cows in the pen.

Returns

float

The average milk production reduction for the cows in the pen (kg).

property average_milk_production_reduction: float

Calculate the average milk production reduction for the cows in the pen.

Returns

float

The average milk production reduction for the cows in the pen (kg).

property total_enteric_methane: float

Calculate the total enteric methane produced by all animals in the pen on the current day (g).

_initialize_beddings() → None

Initialize all beddings for manure streams in the pen.

reset_milk_production_reduction() → None

Resets the milk production reduction to 0 for all animals in the pen.

reduce_milk_production() → bool

Attempts to reduce the milk production of all animals in the pen.

Returns

bool

False if all animals in the pen have already reached the maximum reduction, True otherwise.

remove_animals_by_ids(animal_ids: list[int]) → None

Removes animals from the pen by their ids.

Notes

Because this method takes O(n) time, it is recommended that the caller of this method should prepare a list of animal ids to be removed from the pen first, and then call this method with that list once.

Parameters

animal_idsList[int]

List of animals that match the given ids to be removed from the pen.

Returns

None

update_animals(new_animals: list[Animal], animal_combination: AnimalCombination, available_feeds: list[Feed]) → None

Calls functions that will add new animals to the pen and update associated attributes.

Parameters

new_animals: List[Calf | Cow | HeiferI | HeiferII | HeiferIII]

list of new animals to be added to the pen

animal_combination: AnimalCombination

an AnimalCombination Enum representing the type of the new animals

available_feedslist[Feed]

Nutrition information of feeds available formulate animals rations with.

Returns

None

_add_new_animals(new_animals: list[Animal], available_feeds: list[Feed]) → None

Adds all animals in new_animals to the pen animals_in_pen map, and set the nutrition requirements and the nutrition supply for each new animal.

Parameters

new_animals: List[Calf | Cow | HeiferI | HeiferII | HeiferIII]

list of new animals to be added to the pen

available_feedslist[Feed]

Nutrition information of feeds available formulate animals rations with.

Returns

None

insert_animals_into_animals_in_pen_map(animals: list[Animal]) → None

This method will add a list of new animals in the animals_in_pen map and set the daily walking distance for all the new cows.

Parameters

animals : list[Animal]

Returns

None

Notes

This method only inserts a list of new animals in the animals_in_pen map, and updates the daily walking distance for all the new cows. It does not set the nutrition requirements or the nutrient supply of the new animals, nor does it update pen attributes like ration or animal combination. This method is intended to assign animals to pen during the initialization process where no ration is set for the pen.

insert_single_animal_into_animals_in_pen_map(animal: Animal) → None

This method will add a new animal in the animals_in_pen map and set the daily walking distance if the new animal is a cow.

Parameters

animal: Animal

The animal to insert into pen.

Returns

None

Notes

This method only inserts a new animal in the animals_in_pen map, and updates the daily walking distance if it is a cow. It does not set the nutrition requirements or the nutrient supply of the new animal, nor does it update pen attributes like ration or animal combination.

update_animal_combination(animal_combination: AnimalCombination) → None

Sets the pen’s animal combination to animal_combination

Parameters

animal_combination: AnimalCombination

the new AnimalCombination

Returns

None

update_daily_walking_distance() → None

Updates the daily walking distance for cows in the pen.

Returns

None

clear() → None

Clears the pen attributes for re-allocation.

Notes

All other attributes are kept the same so that if a pen becomes empty and animals are to be added to it, there are previous initial values that are non-zero.

Returns

None

get_manure_streams() → dict[str, ManureStream]

Constructs and returns ManureStream objects based on total manure excreted in a pen and user-defined stream splitting proportions. The ManureStream objects created here are representative of the total manure produced by the animals in any given pen.

For pens with lactating cows, manure is partitioned between a parlor stream and general stream(s). For all other animal combinations, manure is routed only to general stream(s). The split ratios for general streams are user-defined and validated to sum to 1.0.

Returns

dict[str, ManureStream]:

A dictionary mapping a pen ID to a list of dictionaries. Each dictionary within this list maps a stream name to a ManureStream object representing a portion of the pen’s total manure.

Notes

• The function first constructs a total_stream representing the full manure excretion from a pen.

• If the animal combination is LAC_COW, a portion of this stream is split to a parlor stream

based on the minutes_away_for_milking ratio using the split_stream method. - The remaining manure is split into one or more general streams according to the proportions specified in self.manure_streams and each assigned a first_processor directing it how to be routed once it reaches the manure module. - The function validates that all general stream proportions sum to 1.0 (or 100% of the general portion).

_apply_bedding(manure_stream: ManureStream, bedding_name: str) → ManureStream

Applies bedding to the given manure stream.

Parameters

manure_streamManureStream

The manure stream object.

bedding_namestr

The name of the bedding, this should correspond to a key in the beddings attribute.

Returns

ManureStream

A new ManureStream object with updated attributes reflecting the impact of the applied bedding.

_calculate_manure_surface_area() → float

Get the exposed manure surface area based on the pen type and whether there are lactating cows in the pen.

Notes

The exposed manure surface area is looked up from the following table:

Pen Type	Has Lac Cows	No Lac Cows
Freestall	3.5	2.5
Tiestall	1.2	1.0
Compost Bedded Pack Barn	5.0	3.0
Open Lot	5.0	3.0

Returns

float

Exposed manure surface area (\(m^2\)).

Raises

ValueError

If the pen type is not one of the following: “freestall”, “tiestall”, “compost bedded pack barn”, or “open lot”.

_validate_general_manure_stream_proportions() → None

Validates that the proportions of general manure streams sum to 1.0.

Raises

ValueError

If the sum of the proportions is not equal to 1.0.

set_animal_nutritional_requirements(temperature: float, available_feeds: list[Feed]) → None

Set the nutritional requirements for all animals in the pen.

Parameters

temperaturefloat

The temperature of the pen (C).

available_feedslist[Feed]

Nutrition information of feeds available to formulate animals rations with.

Returns

None

set_animal_nutritional_supply(feeds_used: list[Feed], ration_formulation: dict[int, float]) → None

Set the nutritional supply for all animals in the pen.

Parameters

feeds_usedlist[Feed]

The list of feeds used to formulate the ration.

ration_formulationdict[RUFAS_ID, float]

The formulated ration dictionary, mapping RuFaS Feed ID to mass of feed in ration per animal per day.

Returns

None

formulate_optimized_ration(pen_available_feeds: list[Feed], temperature: float, max_daily_feeds: dict[int, float], advance_purchase_allowance: AdvancePurchaseAllowance, total_inventory: TotalInventory) → None

Formulates a ration while optimizing for multiple goals.

Parameters

pen_available_feedslist[Feed]

List of feeds available to formulate a new ration with for a pen.

max_daily_feedsdict[RUFAS_ID, float]

Maximum amounts of each feed type that may be fed per animal per day.

advance_purchase_allowanceAdvancePurchaseAllowance

Maximum amounts of each feed type that may be purchased at the beginning of a feed interval.

total_inventoryTotalInventory

Amounts of feeds currently held in storage.

Returns

None

use_user_defined_ration(pen_available_feeds: list[Feed], temperature: float) → None

Calculate new ration for the pen based on the number of animals in the pen.

Parameters

pen_available_feedslist[Feed]

List of available feeds to be used in the ration formulation.

temperaturefloat

Temperature of the animals’ environment (°C).

Notes

The average nutrition requirements of the pen are calculated, and then used to determine the ration given to each animal. Then ration is checked against the nutrition requirements of every individual animal in the pen. If the animal is a lactating cow and the ration does not meet its requirements, then its milk production is reduced until one of three conditions is met: 1. The ration meets the animal’s requirement. 2. The milk production of the animal is reduced by the maximum amount allowed. 3. The average milk production of the pen falls below the minimum allowable average milk production.

If the animal is not a lactating cow, the outcomes of that animal are not affected and its nutrition requirements are not met.

Returns

None

get_requested_feed(ration_interval_length: int) → RequestedFeed

Returns the requested feed for the pen.

Parameters

ration_interval_lengthint

The length of the ration interval (days).

Returns

RequestedFeed

The requested feed for the pen.