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, int amr_level, 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_amr_level = 0
	AMR level this instance reports for. 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:

Each AMR level owns its own RadiationDiagnostics, so the identity below is implicitly per level: two levels reporting the same step, call_site and time are distinct instances and neither suppresses the other. All instances append to the same CSV, which carries a level column to tell the rows apart.

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,
		int	amr_level,
		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 this instance reports for. Written as the level CSV column and tagged onto the stdout lines. One instance per level, so the duplicate guard below is per level and a fine level's row is never mistaken for a coarse one.
[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_amr_level(amr_level),
    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) [optional]: T_s_mean, T_s_max, q_s_mean, q_s_max level – appended last, following this file's rule that new columns go at the end so existing header-name parsers keep working.

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)
  // One instance per AMR level, so this state is per level and a fine level
  // never suppresses a coarse level's row at the same step and 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] level=" << m_amr_level
                   << " 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: level=" << m_amr_level
                   << " 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;
 
  // AMR level (see write_header_if_needed)
  outfile << "," << m_amr_level;
 
  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";
    // AMR level, appended last for the same backward-compatibility reason as
    // the columns above: consumers index by header name, not position.
    outfile << ",level";
    outfile << "\n";
  }
  outfile.close();
  m_header_written = true;
}

Referenced by append().

Here is the caller graph for this function:

Member Data Documentation

m_amr_level

int RadiationDiagnostics::m_amr_level = 0

private

AMR level this instance reports for.

Referenced by append().

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