feature(#30): Add detailed catch output per species per box per fishery

[jacobkasper]

closes #30

Summary

Adds a new optional output file OutDetailedCatch.txt that reports annual catch by species, box, and fishery. This fills a gap in the existing outputs — OutCatch.txt reports total catch per species (no fishery or box dimensions), OutCatchPerFishery.txt reports catch per fishery per species (no box dimension), and the Out.nc file contains no catch variables. The new file provides the full species × box × fishery breakdown needed for spatial fisheries analysis such as MPA impact evaluation.

New parameter

flagdetailedcatch — added to Run.prm (read via XML pipeline)

• 0 = off (default), no file created
• 1 = on, OutDetailedCatch.txt is written annually

Output file format

Time Box Fishery FCD FHA FSA FRF FGH ...
3.650000e+02 0 long 0.000000e+00 0.000000e+00 ...
3.650000e+02 1 long 0.000000e+00 0.000000e+00 ...

• One row per box per fishery per year
• Columns are fished species only (isFished == TRUE)
• Catch values in tonnes (converted from mg N using X_CN * mg_2_tonne)
• Written annually, before CumCatch is reset
• Catch is summed over water column layers per box

Files changed

File	Changes
atlantisboxmodel.h	Added int flagdetailedcatch field
atparamIO.c	Read flagdetailedcatch from XML config
atRunXML.c	Create XML node with default value 0
atHarvestIO.c	Added initDetailedCatchFile(), writeDetailedCatch(), file pointer, forward declarations; added calls in Open_Harvest_Output_Files, Close_Harvest_Output_Files, Harvest_Report_Annual_Stats

Usage

Add to Run.prm:

flagdetailedcatch    1    0=off, 1=detailed catch per species per box per fishery

---

Validation

Compared OutDetailedCatch.txt (summed across all boxes and fisheries) against OutCatch.txt for FCD. The ratio is consistently ~0.9985 across all years. The small ~0.15% discrepancy is due to OutCatch.txt using a separately accumulated TotCumCatch variable while OutDetailedCatch.txt sums CumCatch[sp][nf][box][layer] directly. Minor floating-point accumulation differences across thousands of timesteps account for the gap.

---

Notes

• File can be large: (number of boxes × number of fisheries × number of years) rows
• Only species with isFished = 1 in the groups CSV are included
• The file is written at the same time as other annual harvest outputs, just before CumCatch is reset

---

[hmorzaria]

@jacobkasper did you see this #32 is failing when running the SETAS model? The error is:
Atlantis Failed to run due to a missing parameter Error in tests() : Could not find parameter 'flagdetailedcatch' in input file VMPA_setas_run_fishing_F_Trunk.prm

Since you added a new flag @andybeet will have to update the SETAS parameter files at some point, not sure when is the right time to do this?

[andybeet]

@hmorzaria Thanks, i didn't catch this!! @jacobkasper, like Hem said we should update the SETAS run.prm and add the flag flagdetailedcatch to it. Typically we would want to use the default value (0) but this code change is focused on additional output so we might want to use value of 1 and test the code. Especially since this new flag doesn't require additional parameters or additional calibration. That way the code responsible for writing the output will be tested when the example runs.

Preferably, the SETAS example should be added to this PR to ensure all checks pass!

[andybeet]

@jacobkasper looks great! Thanks

[jacobkasper]

@andybeet @hmorzaria I added the prm to the example run.prm and all checks have passed

[andybeet]

Yeah, looks good to me