Add unset capability for ParmParse (#5263)

## Summary

For ParmParse, once a variable is set in an input file, there is no way
to remove it completely from the command line or subsequently in the
input file. For example, you may have specified `amr.keyword = 5` in
`inputs.inp` but then want to override it on the command line so a check
on `pp.contains("amr.keyword")` comes up as false. Right now, using
command line input overrides you can set it to a null value but not
completely remove it from the table (pp.remove() can remove from the
table in source code).

This PR adds an UNSET directive to ParmParse that removes a
previously-defined keyword from the parse table. This enables input
files to conditionally suppress parameters — for example, an included
file can cancel a key set by its parent.
```
amr.keyword = 5
UNSET = amr.keyword
# equivalent to never having set amr.keyword
```

Multiple keys can be removed in a single directive:
```
UNSET = key1 key2 key3
```

## Additional background

Motivated by discussion in
Exawind/amr-wind#1897. Code generated by
Copilot.

Mirrors the design of the existing FILE directive. The new
`ParmParse::UnsetKeyword = "UNSET"` static is exposed in the header for
symmetry with FileKeyword. The directive is handled in addDefn() by
erasing each listed key from the table; keys not present are silently
ignored.

Tests added to Tests/ParmParse/inputs and Tests/ParmParse/main.cpp cover
single-key unset, multi-key unset, and verifying that non-listed keys
are unaffected.

## Checklist

The proposed changes:
- [ ] fix a bug or incorrect behavior in AMReX
- [X] add new capabilities to AMReX
- [ ] changes answers in the test suite to more than roundoff level
- [ ] are likely to significantly affect the results of downstream AMReX
users
- [X] include documentation in the code and/or rst files, if appropriate

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: baperry2

Docs/sphinx_documentation/source/Basics.rst

@@ -668,6 +668,21 @@ entries in an inputs file:
    hydro.cfl = 0.9
    my_string = "A String"
 
+You can also remove the effect of having defined an input parameter at all using the
+``UNSET`` directive (parameters that are merely overridden will still be caught by
+:cpp:`pp.contains()` checks in code). Specifying ``keyword = 5`` in an input file and
+then ``UNSET = keyword`` subsequently in the input file or from the command line
+completely removes ``keyword`` from the ParmParse table. Multiple keywords can
+be removed simultaneously (``UNSET = key1 key2 key3``). if using the ``UNSET``
+directive with TOML-like input files, note that full parameter names must be used
+even if the UNSET falls within a TOML table:
+
+.. code-block:: none
+
+   [x]
+   a = 1  # Same as x.a = 1 at the root level
+
+   UNSET = x.a # full name required to remove x.a entry
 
 Setting Defaults via an Environment Variable
 --------------------------------------------

Src/Base/AMReX_ParmParse.H

@@ -1773,6 +1773,9 @@ public:
     //! keyword for files to load
     static std::string const FileKeyword;
 
+    //! keyword for removing entries from the table
+    static std::string const UnsetKeyword;
+
     static std::string ParserPrefix;
 
     [[nodiscard]] std::string const& getPrefix () const;

Src/Base/AMReX_ParmParse.cpp

@@ -40,6 +40,7 @@ namespace {
 }
 
 std::string const ParmParse::FileKeyword = "FILE";
+std::string const ParmParse::UnsetKeyword = "UNSET";
 std::string       ParmParse::ParserPrefix;
 
 ParmParse::ParmParse (std::string prefix, std::string parser_prefix)
@@ -772,6 +773,15 @@ addDefn (std::string& def, std::vector<std::string>& val,
         read_file(fname, tab);
         g_toml_table_key = std::move(prev_toml_table_key);
     }
+    //
+    // Check if this defn is an unset directive.
+    //
+    else if ( def == ParmParse::UnsetKeyword )
+    {
+        for (auto const& key : val) {
+            tab.erase(key);
+        }
+    }
     else
     {
         std::string key;

Tests/ParmParse/inputs

@@ -156,3 +156,13 @@ macro.use_gpu.spacedim = 3
 #  endif
 
 #endif
+
+# UNSET directive tests
+unset_me = 123
+UNSET = unset_me
+
+unset_multi_a = 1
+unset_multi_b = 2
+UNSET = unset_multi_a unset_multi_b
+
+unset_kept = 77

Tests/ParmParse/main.cpp

@@ -335,6 +335,21 @@ int main(int argc, char* argv[])
         int n = pp.countname("string-for-testing-addfile");
         AMREX_ALWAYS_ASSERT(n==3 && s == "string for testing addfile");
     }
+    { // UNSET directive
+        ParmParse pp;
+        // "unset_me" is defined then immediately unset in the inputs file
+        int v = -1;
+        int found = pp.query("unset_me", v);
+        AMREX_ALWAYS_ASSERT(found == 0);
+        // "unset_multi_a" and "unset_multi_b" are unset together in inputs
+        found = pp.query("unset_multi_a", v);
+        AMREX_ALWAYS_ASSERT(found == 0);
+        found = pp.query("unset_multi_b", v);
+        AMREX_ALWAYS_ASSERT(found == 0);
+        // "unset_kept" is NOT unset, so it should still be present
+        pp.get("unset_kept", v);
+        AMREX_ALWAYS_ASSERT(v == 77);
+    }
     {
         amrex::Print() << "SUCCESS\n";
     }