Add binary file_format for gauge in 1D

[yingjie1234]

#308 This is starting point to fix gauge format. Please give me suggestions on this.

New per-gauge option:
rundata.gaugedata.file_format = 'binary32' (or 'binary64', 'ascii'); defaults to ASCII if unspecified.

New file types:
Each gauge can now write to gaugeXXXXXX.bin with a short ASCII header (e.g., # file_format: binary32).

Binary layout:
[level :: int32] [time :: float32/float64] [q(1:nvar) :: float32/float64]

Buffer management:

Added flush_all_gauges() to write any buffered data during checkpoints.

Updated print_gauges_and_reset_nextLoc() to handle binary output modes.

Example & test:
Updated examples/advection_1d_example1/setrun.py to demonstrate binary mode.
Added src/1d/verify.py — a small Python script using NumPy to read and verify .bin gauge files.

[yingjie1234]

@mandli I uploaded my code again, how to test it again on your side?

[mandli]

@yingjie1234 I just approved the testing. You should get the results shortly.

[rjleveque]

@yingjie1234 - Thanks for working on this and sorry to be slow to look at this. I haven't gone through the code carefully, but I tried running the example in examples/advection_1d_example1 and noted the following:

It runs fine when I set

rundata.gaugedata.file_format = 'binary32'     # <= single string

or the other options as a string, but setting

rundata.gaugedata.file_format = 2

throws an error

 File "/Users/rjl/git/clawpack/amrclaw/src/python/amrclaw/data.py", line 446, in write
    file_format = format_map[self.file_format[gauge_num].lower()]
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'int' object has no attribute 'lower'

with a similar error if it's set to any list.

Also, running pytest, the test passes for 'ascii' but not for the binary choices.

[yingjie1234]

@mandli could you guide on the testing on this part? I can fix this error. thanks!

[mandli]

What we need is to modify one of the tests to also write out the gauges in every format and compare them. I would take the test that you have modified and add a gauge for each format and write code that then reads in the gauges and compares them to each other. Does that make sense?

[yingjie1234]

Yes, I will test it then get back to you soon.

[yingjie1234]

Summary: Add Binary Gauge Output Support (binary32 / binary64)

This PR introduces optional binary gauge output to AMRClaw, while keeping ASCII as the default and fully backward-compatible.
It adds finer control over gauge file formats, improves performance for large simulations, and includes a verification tool.

---

Key Features

1. New file_format options (scalar or per-gauge)

Users can now specify gauge output formats using either strings or integers:

# Global format
rundata.gaugedata.file_format = "ascii"      # or 1
rundata.gaugedata.file_format = "binary32"   # or 2
rundata.gaugedata.file_format = "binary64"   # or 3

# Per-gauge format
rundata.gaugedata.file_format = ["ascii", "binary32"]
rundata.gaugedata.file_format = [1, 2]

2. Updated gauges.data writer

# File format (1=ascii, 2=binary32, 3=binary64)
2 2

3. Fortran support for binary gauge writers

Binary files (gaugeXXXXX.bin) use unformatted stream output with layout:

• level :: int32
• time :: float32 / float64
• q(1:nvar) :: float32 / float64

Each file contains a one-line ASCII header:

# file_format: binary32

4. Added verification tool

src/1d/verify.py reads .bin gauge files using NumPy and prints:

_output/gauge00000.bin 4950 rows; first3: [...]
_output/gauge00001.bin 5160 rows; first3: [...]

---

Testing

• Ran examples/advection_1d_example1 with:
  • default ASCII,
  • file_format = ["binary32", "binary32"],
  • file_format = [2, 2].
• Verified correct gauges.data output (2 2) and .bin files.
• Confirmed binary layout via verify.py.
• Restored example defaults to ASCII so regression tests remain valid.
• Full AMRClaw test suite:

14 passed, 0 failed

[mandli]

Thanks @yingjie1234 ! @rjleveque and I will review this and give you feedback if necessary.

[mandli]

Here is some basic feedback from a quick read-through.

[mandli]

May want to clean this up for the example

[mandli]

I would suggest writing a gauge out for every format available and comparing them all as a test, perhaps with unique tolerances if need be. Each gauge could actually be at the same location, just different formats (just for the test).

[yingjie1234]

yes, I will do that

[mandli]

I should note that the other dimensions could be added to this PR, but as it only modifies the 1D code so far, I wanted to make sure that the current state, if merged, is reflected in the title.

[yingjie1234]

Add per-gauge binary format support and comprehensive tests

• Support per-gauge file formats (ascii, binary32, binary64)
• Move load_bin to amrclaw/util.py for reusability
• Add tests for gauge formats in 1D, 2D, and 3D
• Update example to test all formats simultaneously
• Fix pytest warnings in test functions

[mandli]

Is this generated somewhere?

[yingjie1234]

yes, I did not include it, it only generated on my end.

[mandli]

Can you move the tests to src/python/amrclaw? Were they not being discovered otherwise?

[yingjie1234]

Can you move the tests to src/python/amrclaw? Were they not being discovered otherwise?

yes, I already move the tests to src/python/amrclaw

[rjleveque]

@mandli: is this ready to merge?

I ran the example and it seems fine. The only thing I noticed was the warning

/Users/rjl/git/clawpack/amrclaw/src/1d/gauges_module.f90:33:35:

   33 |     integer, save, allocatable :: gauge_file_format(:)
      |                                   1~~~~~~~~~~~~~~~~~~~
Warning: Legacy Extension: Duplicate SAVE attribute specified at (1)

since save is already at the top of the subroutine.

[mandli]

I don't think it's that big of a deal, but we could remove that save as it is on for all module level variables. Probably should not do that, but I have never been completely clear as to what this does.

I think we can merge this. Now just need to do it for 2D and 3D.