RadiationDiagnostics Class Reference

CSV logger and debug-print manager for radiation module. More...

#include <ERF_RadiationDiagnostics.H>

Collaboration diagram for RadiationDiagnostics:

Public Member Functions
	RadiationDiagnostics (int verbosity, const std::string &diag_file, bool diag_enable=true, bool diag_stdout_enable=true, bool diag_tagged_enable=true, bool diag_regtest_line_enable=true, bool diag_csv_enable=true, const std::string &diag_callsite_mode="both", amrex::Real diag_dedup_tol=1.0e-12)
	Constructor. More...
	~RadiationDiagnostics ()
	Destructor. More...
void	append (int step, amrex::Real time, std::string const &call_site, amrex::Real sw_surface, amrex::Real sw_toa, amrex::Real sw_up_toa, amrex::Real lw_net_surface, amrex::Real lw_up_toa, amrex::Real heating_rate_max, amrex::Real seb_residual_mean=std::numeric_limits< amrex::Real >::quiet_NaN(), amrex::Real seb_residual_max=std::numeric_limits< amrex::Real >::quiet_NaN(), amrex::Real t_s_mean=std::numeric_limits< amrex::Real >::quiet_NaN(), amrex::Real t_s_max=std::numeric_limits< amrex::Real >::quiet_NaN(), amrex::Real q_s_mean=std::numeric_limits< amrex::Real >::quiet_NaN(), amrex::Real q_s_max=std::numeric_limits< amrex::Real >::quiet_NaN())
	Append a diagnostic row to the CSV file. More...

Private Member Functions
void	write_header_if_needed ()
	Write CSV header if file is new or doesn't exist. More...

Private Attributes
int	m_verbosity
	Debug verbosity level. More...
std::string	m_diag_file
	Output CSV file path. More...
int	m_last_write_step = -1
	Guard against duplicate writes. More...
bool	m_header_written = false
	Track whether CSV header was written. More...
std::string	m_last_write_call_site = ""
amrex::Real	m_last_write_time = -1.0
bool	m_diag_enable = true
bool	m_diag_stdout_enable = true
bool	m_diag_tagged_enable = true
bool	m_diag_regtest_line_enable = true
bool	m_diag_csv_enable = true
std::string	m_diag_callsite_mode = "both"
amrex::Real	m_diag_dedup_tol = 1.0e-12

Detailed Description

CSV logger and debug-print manager for radiation module.

Manages output of radiation diagnostics including:

• Tagged debug prints (when verbosity >= 1)
• CSV rows for flux/heating diagnostics
• RADIATION_DIAG: lines for RegTest parsing

Dedup Contract:

Duplicate detection uses a 3-tuple identity (step, call_site, time):

• step: timestep number (int)
• call_site: diagnostic call-site label (e.g., "pre_dycore", "post_dycore")
• time: simulation time with tolerance m_diag_dedup_tol

This ensures:

1. Accidental repeated calls at the same (step, call_site, time) are suppressed.
2. Legitimate pre_dycore + post_dycore entries at the same step are both retained (they have different call_site values, so dedup identity differs).
3. Mode filtering (pre_only, post_only, both) preserves this contract by checking whether to emit BEFORE the dedup guard runs.

Follows the duplicate-write-guard pattern from UCMDiagnostics.

Constructor & Destructor Documentation

RadiationDiagnostics()

RadiationDiagnostics::RadiationDiagnostics	(	int	verbosity,
		const std::string &	diag_file,
		bool	diag_enable = true,
		bool	diag_stdout_enable = true,
		bool	diag_tagged_enable = true,
		bool	diag_regtest_line_enable = true,
		bool	diag_csv_enable = true,
		const std::string &	diag_callsite_mode = "both",
		amrex::Real	diag_dedup_tol = 1.0e-12
	)

Constructor.

Parameters

[in]	verbosity	Debug verbosity level (0=off, 1+=print).
[in]	diag_file	Output CSV file path (relative to working directory).
[in]	amr_level	AMR level index.
[in]	diag_enable	Master switch for all diagnostics.
[in]	diag_stdout_enable	Enable human-readable stdout block.
[in]	diag_tagged_enable	Enable tagged debug lines.
[in]	diag_regtest_line_enable	Enable RADIATION_DIAG: lines.
[in]	diag_csv_enable	Enable CSV file writes.
[in]	diag_callsite_mode	Call-site filter: "both", "pre_only", "post_only".
[in]	diag_dedup_tol	Tolerance for time equality in duplicate guard.

  : m_verbosity(verbosity), m_diag_file(diag_file),
    m_diag_enable(diag_enable), m_diag_stdout_enable(diag_stdout_enable),
    m_diag_tagged_enable(diag_tagged_enable),
    m_diag_regtest_line_enable(diag_regtest_line_enable),
    m_diag_csv_enable(diag_csv_enable), m_diag_callsite_mode(diag_callsite_mode),
    m_diag_dedup_tol(diag_dedup_tol)
{
  // Constructor: nothing special needed
  // write_header_if_needed() is called on first append()
}

~RadiationDiagnostics()

RadiationDiagnostics::~RadiationDiagnostics

(

)

Destructor.

{
  // Destructor: nothing special needed
  // File handles are closed by ofstream RAII
}

Member Function Documentation

append()

void RadiationDiagnostics::append	(	int	step,
		amrex::Real	time,
		std::string const &	call_site,
		amrex::Real	sw_surface,
		amrex::Real	sw_toa,
		amrex::Real	sw_up_toa,
		amrex::Real	lw_net_surface,
		amrex::Real	lw_up_toa,
		amrex::Real	heating_rate_max,
		amrex::Real	seb_residual_mean = std::numeric_limits<amrex::Real>::quiet_NaN(),
		amrex::Real	seb_residual_max = std::numeric_limits<amrex::Real>::quiet_NaN(),
		amrex::Real	t_s_mean = std::numeric_limits<amrex::Real>::quiet_NaN(),
		amrex::Real	t_s_max = std::numeric_limits<amrex::Real>::quiet_NaN(),
		amrex::Real	q_s_mean = std::numeric_limits<amrex::Real>::quiet_NaN(),
		amrex::Real	q_s_max = std::numeric_limits<amrex::Real>::quiet_NaN()
	)

Append a diagnostic row to the CSV file.

Records a row of radiation diagnostics for the current timestep:

CSV columns (order): step, time, call_site, SW_surface, SW_TOA, SW_up_TOA, LW_net_surface, LW_up_TOA, heating_rate_max [optional]: SEB_residual_mean, SEB_residual_max (only if seb_diagnostic_enable=true)

Also prints tagged debug output and RADIATION_DIAG: line for RegTest parsing.

Guards against duplicate writes (uses m_last_write_step).

Parameters

[in]	step	Current timestep number.
[in]	time	Current simulation time [s].
[in]	call_site	Diagnostic call-site label (e.g., "pre_dycore", "post_dycore").
[in]	SW_surface	SW absorbed by the surface, (1 - albedo) * incident [W/m^2].
[in]	SW_TOA	Incident SW at the top of the atmosphere [W/m^2].
[in]	SW_up_TOA	Reflected SW leaving the top of the atmosphere [W/m^2].
[in]	LW_net_surface	Net LW (up - down) at the surface [W/m^2].
[in]	LW_up_TOA	Outgoing LW at the top of the atmosphere [W/m^2].
[in]	heating_rate_max	Maximum heating rate magnitude [K/s].
[in]	seb_residual_mean	[optional] Mean SEB residual [W/m^2]; if non-finite, not written.
[in]	seb_residual_max	[optional] Max SEB residual [W/m^2]; if non-finite, not written.
[in]	t_s_mean	[optional] Mean surface temperature [K]; if non-finite, written as NaN.
[in]	t_s_max	[optional] Max surface temperature [K]; if non-finite, written as NaN.
[in]	q_s_mean	[optional] Mean surface moisture [kg/kg]; if non-finite, written as NaN.
[in]	q_s_max	[optional] Max surface moisture [kg/kg]; if non-finite, written as NaN.

{
  // Master enable gate
  if (!m_diag_enable) {
    return;
  }
 
  // Call-site mode filtering
  bool should_emit_pre = (m_diag_callsite_mode == "both" || m_diag_callsite_mode == "pre_only");
  bool should_emit_post = (m_diag_callsite_mode == "both" || m_diag_callsite_mode == "post_only");
 
  bool is_pre_site = (call_site.find("pre") != std::string::npos);
  bool is_post_site = (call_site.find("post") != std::string::npos);
 
  // Check if this call site should be filtered based on mode
  if ((is_pre_site && !should_emit_pre) || (is_post_site && !should_emit_post)) {
    return;
  }
 
  // Guard against duplicate writes using 3-tuple identity:
  //   (step, call_site, time)
  // This ensures:
  // 1. Accidental repeated calls at same (step, call_site, time) are suppressed.
  // 2. Legitimate pre_dycore + post_dycore entries at same step both retained
  //    (different call_site values, so identity tuple differs).
  // 3. Mode filtering above already runs first, so pre_only/post_only modes
  //    naturally prevent unwanted entries from reaching this dedup logic.
  //
  // Time tolerance (m_diag_dedup_tol) accounts for floating-point rounding when
  // multiple diagnostics functions are called at effectively the same time.
  if (step == m_last_write_step &&
      call_site == m_last_write_call_site &&
      std::abs(time - m_last_write_time) < m_diag_dedup_tol) {
    return;  // Duplicate detected; skip write
  }
  m_last_write_step = step;
  m_last_write_call_site = call_site;
  m_last_write_time = time;
 
  // Print debug output (if verbosity >= 1, and IOProcessor only)
  //
  // The bracketed tag is the module-generic "[RAD]" plus the call site, so
  // it stays accurate and grepable no matter which radiation feature is
  // driving the call.
  if (m_verbosity >= 1 && amrex::ParallelDescriptor::IOProcessor() &&
      m_diag_tagged_enable && m_diag_stdout_enable) {
    amrex::Print() << "[RAD][RadiationDiagnostics::append] step=" << step
                   << " time=" << time
                   << " call_site=" << call_site
                   << " SW_surface=" << SW_surface
                   << " SW_TOA=" << SW_TOA << " SW_up_TOA=" << SW_up_TOA
                   << " LW_net_surface=" << LW_net_surface
                   << " LW_up_TOA=" << LW_up_TOA
                   << " heating_rate_max=" << heating_rate_max << "\n";
  }
 
  // Print RADIATION_DIAG line (for RegTest scripts)
  if (amrex::ParallelDescriptor::IOProcessor() && m_diag_regtest_line_enable &&
      m_diag_stdout_enable) {
    amrex::Print() << "RADIATION_DIAG: step=" << step << " time=" << time
                   << " call_site=" << call_site
                   << " SW_surface=" << std::scientific << std::setprecision(6)
                   << SW_surface << " SW_TOA=" << SW_TOA << " SW_up_TOA=" << SW_up_TOA
                   << " LW_net_surface=" << LW_net_surface << " LW_up_TOA=" << LW_up_TOA
                   << " heating_rate_max=" << heating_rate_max << "\n";
  }
 
  // Append CSV row
  if (!amrex::ParallelDescriptor::IOProcessor() || !m_diag_csv_enable) {
    return;
  }
 
  write_header_if_needed();
 
  std::ofstream outfile(m_diag_file, std::ios::app);
  if (!outfile.good()) {
    amrex::Warning("RadiationDiagnostics: Could not open file " + m_diag_file +
                   " for append");
    return;
  }
 
  // Write CSV row with scientific notation for fluxes
  outfile << step << "," << std::scientific << std::setprecision(6) << time << ","
          << call_site << ","
          << SW_surface << "," << SW_TOA << "," << SW_up_TOA << "," << LW_net_surface << "," << LW_up_TOA
          << "," << heating_rate_max;
 
  // Append SEB residual columns (backward compatible: write NaN if not available)
  outfile << "," << seb_residual_mean << "," << seb_residual_max;
 
  // Append prognostic T_s and q_s columns (backward compatible: write NaN if not available)
  outfile << "," << t_s_mean << "," << t_s_max << "," << q_s_mean << "," << q_s_max;
 
  outfile << "\n";
  outfile.close();
}

Referenced by TwoStreamRadiation::advance().

Here is the call graph for this function:

Here is the caller graph for this function:

write_header_if_needed()

void RadiationDiagnostics::write_header_if_needed ( )

private

Write CSV header if file is new or doesn't exist.

{
  if (m_header_written || !m_diag_csv_enable || !m_diag_enable) {
    return;
  }
 
  if (!amrex::ParallelDescriptor::IOProcessor()) {
    m_header_written = true;
    return;
  }
 
  // Check if file already exists (append vs. new)
  std::ifstream infile(m_diag_file);
  bool file_exists = infile.good();
  infile.close();
 
  std::ofstream outfile(m_diag_file, std::ios::app);
  if (!outfile.good()) {
    amrex::Warning("RadiationDiagnostics: Could not open file " + m_diag_file);
    m_header_written = true;
    return;
  }
 
  // Only write header if file is new
  if (!file_exists) {
    // Base columns: always present
    outfile << "step,time,call_site,SW_surface,SW_TOA,SW_up_TOA,LW_net_surface,LW_up_TOA,heating_rate_max";
    // SEB diagnostic columns (added at end for backward compatibility)
    outfile << ",SEB_residual_mean,SEB_residual_max";
    // SEB prognostic surface temperature and moisture columns
    outfile << ",T_s_mean,T_s_max,q_s_mean,q_s_max";
    outfile << "\n";
  }
  outfile.close();
  m_header_written = true;
}

Referenced by append().

Here is the caller graph for this function:

Member Data Documentation

m_diag_callsite_mode

std::string RadiationDiagnostics::m_diag_callsite_mode = "both"

private

Referenced by append().

m_diag_csv_enable

bool RadiationDiagnostics::m_diag_csv_enable = true

private

Referenced by append(), and write_header_if_needed().

m_diag_dedup_tol

amrex::Real RadiationDiagnostics::m_diag_dedup_tol = 1.0e-12

private

Referenced by append().

m_diag_enable

bool RadiationDiagnostics::m_diag_enable = true

private

Referenced by append(), and write_header_if_needed().

m_diag_file

std::string RadiationDiagnostics::m_diag_file

private

Output CSV file path.

Referenced by append(), and write_header_if_needed().

m_diag_regtest_line_enable

bool RadiationDiagnostics::m_diag_regtest_line_enable = true

private

Referenced by append().

m_diag_stdout_enable

bool RadiationDiagnostics::m_diag_stdout_enable = true

private

Referenced by append().

m_diag_tagged_enable

bool RadiationDiagnostics::m_diag_tagged_enable = true

private

Referenced by append().

m_header_written

bool RadiationDiagnostics::m_header_written = false

private

Track whether CSV header was written.

Referenced by write_header_if_needed().

m_last_write_call_site

std::string RadiationDiagnostics::m_last_write_call_site = ""

private

Referenced by append().

m_last_write_step

int RadiationDiagnostics::m_last_write_step = -1

private

Guard against duplicate writes.

Referenced by append().

m_last_write_time

amrex::Real RadiationDiagnostics::m_last_write_time = -1.0

private

Referenced by append().

m_verbosity

int RadiationDiagnostics::m_verbosity

private

Debug verbosity level.

Referenced by append().

---

The documentation for this class was generated from the following files:

• Source/Radiation/TwoStream/ERF_RadiationDiagnostics.H
• Source/Radiation/TwoStream/ERF_RadiationDiagnostics.cpp