Run complete FB4 simulation (Mid-level - Main function) — run_fb4

Main simulation function that executes the complete FB4 model day by day. Handles different consumption methods and optional daily output. Performs basic validation of critical parameters.

Usage

run_fb4_simulation(
  consumption_method,
  processed_simulation_data,
  oxycal = 13560,
  output_daily = TRUE,
  verbose = FALSE
)

Arguments

consumption_method: List with method type and value
processed_simulation_data: Complete processed simulation data from prepare_simulation_data()
oxycal: Oxycalorific coefficient (J/g O2), default 13560
output_daily: Whether to save daily outputs, default TRUE
verbose: Whether to show progress messages, default FALSE

Value

A named list with up to eleven elements:

initial_weight: Numeric. Starting fish weight (g).
final_weight: Numeric. Fish weight at end of simulation (g); minimum 0.01 g.
weight_change: Numeric. Net change in weight (g).
relative_growth: Numeric. Relative growth as percentage of initial weight.
total_consumption_g: Numeric. Cumulative consumption over all simulated days (g prey).
total_consumption: Numeric. Alias for total_consumption_g (retained for backward compatibility).
simulation_days: Integer. Number of days actually simulated; may be less than the full duration if mortality occurs.
method: List. The consumption_method supplied by the caller.
simulation_completed: Logical. TRUE if the simulation ran for all requested days without early termination.
mortality_occurred: Logical. TRUE if fish weight fell to or below 0.01 g during the simulation.
daily_output: A data.frame with one row per simulated day containing temperature, consumption, respiration, egestion, excretion, net energy, weight, and energy density. Only present when output_daily = TRUE.

Examples

# \donttest{
# Requires processed simulation data; see ?prepare_simulation_data
# sim <- run_fb4_simulation(
#   consumption_method = list(type = "p_value", value = 0.5),
#   processed_simulation_data = sim_data
# )
# sim$final_weight
# }