run_fb4_simulation: Run complete FB4 simulation (Mid-level - Main function)

In fb4package: 'Fish Bioenergetics 4.0' Model Implementation with High-Performance 'TMB' Backend

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

Description

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

# 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

fb4package documentation built on May 8, 2026, 1:07 a.m.