diff --git a/cmac/cmac_radar.py b/cmac/cmac_radar.py index fff5bc4..29e8c5a 100644 --- a/cmac/cmac_radar.py +++ b/cmac/cmac_radar.py @@ -38,6 +38,20 @@ def _get_field_fill_value(field): "Bringi requires a missing-data value, but the field defines none") +def _get_bringi_options(cmac_config): + """Return validated Bringi filter options from a CMAC configuration.""" + nfilter = cmac_config.get('bringi_nfilter', 1) + window = cmac_config.get('bringi_window', 3.0) + if (isinstance(nfilter, (bool, np.bool_)) or + not isinstance(nfilter, (int, np.integer)) or nfilter < 1): + raise ValueError('bringi_nfilter must be a positive integer') + if (isinstance(window, (bool, np.bool_)) or + not isinstance(window, (int, float, np.integer, np.floating)) or + not np.isfinite(window) or window <= 0): + raise ValueError('bringi_window must be a positive finite number') + return {'nfilter': int(nfilter), 'window': float(window)} + + def add_clutter_map(radar, clutter_radar, field_name='ground_clutter'): """Add a clutter map, aligning PPI sweeps by elevation. @@ -448,6 +462,7 @@ def cmac(radar, sonde, config, geotiff=None, flip_velocity=False, elif cmac_config['kdp_method'] == 'bringi': # Bringi's ray-wise retrieval is valid throughout the volume. Unlike # the LP retrieval, do not discard gates above the freezing level. + bringi_options = _get_bringi_options(cmac_config) kdp_gates = copy.deepcopy(cmac_gates) dp_field = radar.fields[field_config['input_phidp_field']] dz_field = radar.fields[field_config['reflectivity']] @@ -482,7 +497,7 @@ def cmac(radar, sonde, config, geotiff=None, flip_velocity=False, dz = np.ma.filled(dz, fill_value) rng = np.tile(radar.range['data'], (radar.nrays, 1)) / 1e3 kdp, phidp, _ = csu_kdp.calc_kdp_bringi(dp=dp, dz=dz, rng=rng, - bad=fill_value) + bad=fill_value, **bringi_options) invalid = (kdp_gates.gate_excluded | dp_mask | dz_mask | (kdp == fill_value) | (phidp == fill_value)) diff --git a/cmac/default_config.py b/cmac/default_config.py index 690b8db..0bc6757 100644 --- a/cmac/default_config.py +++ b/cmac/default_config.py @@ -1312,6 +1312,10 @@ _DEFAULT_PROCESSING_TUNABLES = { 'snow_density': 0.073, 'phidp_nowrap': 50, + # Bringi CSU KDP FIR settings. The window is in km and is passed through + # to csu_kdp.calc_kdp_bringi; nfilter is the number of FIR passes. + 'bringi_nfilter': 1, + 'bringi_window': 3.0, 'kdp_phase_proc_max': 10.0, 'phidp_despeckle_size': 49, 'corrected_velocity_valid_min': -100.0, diff --git a/cmac/tests/test_bringi_settings.py b/cmac/tests/test_bringi_settings.py new file mode 100644 index 0000000..746db68 --- /dev/null +++ b/cmac/tests/test_bringi_settings.py @@ -0,0 +1,34 @@ +"""Tests for YAML-configurable Bringi KDP settings.""" + +import numpy as np +import pytest + +from cmac.cmac_radar import _get_bringi_options + + +def test_bringi_options_default_and_override(): + assert _get_bringi_options({}) == {"nfilter": 1, "window": 3.0} + assert _get_bringi_options( + { + "bringi_nfilter": 2, + "bringi_window": 6, + } + ) == {"nfilter": 2, "window": 6.0} + + +@pytest.mark.parametrize( + "config", + [ + {"bringi_nfilter": 0}, + {"bringi_nfilter": -1}, + {"bringi_nfilter": 1.5}, + {"bringi_nfilter": True}, + {"bringi_window": 0}, + {"bringi_window": -3}, + {"bringi_window": np.inf}, + {"bringi_window": False}, + ], +) +def test_bringi_options_reject_invalid_values(config): + with pytest.raises(ValueError): + _get_bringi_options(config) diff --git a/cmac/tests/test_config.py b/cmac/tests/test_config.py index 6299917..6fd839e 100644 --- a/cmac/tests/test_config.py +++ b/cmac/tests/test_config.py @@ -151,6 +151,8 @@ def test_processing_defaults_present_for_all_radars(): cfg = get_cmac_values(radar) assert cfg['snow_density'] == 0.073 assert cfg['phidp_nowrap'] == 50 + assert cfg['bringi_nfilter'] == 1 + assert cfg['bringi_window'] == 3.0 assert cfg['phidp_despeckle_size'] == 49 assert cfg['melt_fzl_ceiling'] == 5000.0 assert cfg['melt_fzl_replacement'] == 3500.0 @@ -185,6 +187,8 @@ def test_plot_defaults_present_for_all_radars(): xsapr_i5_ppi: snow_density: 0.10 phidp_nowrap: 80 + bringi_nfilter: 2 + bringi_window: 6.0 melt_fzl_ceiling: 6000.0 area_coverage_precip_threshold: 5.0 cbb_blockage_threshold: 0.6 @@ -218,6 +222,8 @@ def test_yaml_overrides_processing_tunables(processing_override_config): cfg = get_cmac_values('xsapr_i5_ppi', config_file=processing_override_config) assert cfg['snow_density'] == 0.10 assert cfg['phidp_nowrap'] == 80 + assert cfg['bringi_nfilter'] == 2 + assert cfg['bringi_window'] == 6.0 assert cfg['melt_fzl_ceiling'] == 6000.0 assert cfg['area_coverage_precip_threshold'] == 5.0 assert cfg['cbb_blockage_threshold'] == 0.6 diff --git a/configs/bnfcsapr2.yaml b/configs/bnfcsapr2.yaml index 2325863..ad67c45 100644 --- a/configs/bnfcsapr2.yaml +++ b/configs/bnfcsapr2.yaml @@ -99,6 +99,9 @@ cmac_values: rain_rate_a_coef_Kdp: 25.1 rain_rate_b_coef_Kdp: 0.777 kdp_method: bringi + # CSU Bringi FIR settings. The window is in km. + bringi_nfilter: 1 + bringi_window: 3.0 # PhiDP system phase offset in degrees. Leave as null to estimate it # from each volume; set a number to pin it. phidp_sys_phase: null diff --git a/documents/cmac_config_reference.md b/documents/cmac_config_reference.md index a307ede..e5d7bbc 100644 --- a/documents/cmac_config_reference.md +++ b/documents/cmac_config_reference.md @@ -214,6 +214,8 @@ them will raise `KeyError` the first time `cmac()` runs. | Key | Meaning | |---|---| | `kdp_method` | `"bringi"` (CSU KDP, default if unset) or `"lp"` (linear-programming, needs COIN-OR/CyLP) | +| `bringi_nfilter` | `1` — number of FIR filter iterations used by the CSU Bringi KDP method | +| `bringi_window` | `3.0` — Bringi FIR window size in km; the resulting filter order must be even | ### Rain rate coefficients (required): `rate = A * moment^B`