Test soudan file and improve docs

[zonca]

• debug soudan
• add soudan to examples
• rough draft of docs about debugging

[zonca]

@pibion a bit of progress here:

I am debugging the stream error that is seen when trying to read the minimal file I created,
I have configured debugging to track down the bug, and in the process I wrote another section of the docs to explain how do do it.

I have identified that the error is in the time_n_minus_veto_mask field in the soudan_history_buffer structure.

I can now:

1. modify the input data file if needed
2. run scala inside the debugger to create the cpp file
3. debug the C++ code parsing the file

All of this inside a single VS Code session

[zonca]

@dchoi here is the first actual debugging task.
The purpose is to understand why reading example_data/data/minimal_sample.soudan fails.

First of all, checkout the test_soudan branch then try to run the tests and confirm that you get an error.

I generated that test file myself using this Jupyter Notebook:

https://github.com/det-lab/cdms_soudan/blob/main/scdms_soudan_minimal_file.ipynb

Therefore you can either use the VS Code line by line debugger and try to understand what is going on, see for example a note I left before in this pull request.

[dchoi]

See if this the output you are looking for. or rephrase the procedure to produce the error you are mentioning.

output.txt

[zonca]

@dchoi ok, I see you were able to execute the notebooks.

Now you should run the C++ tests, so you follow again the procedure at:

https://det-lab.github.io/kaitai_struct_awkward_runtime/development/

but now instead of running on the main branch, you run in the test_soudan branch,
so when you run make test, you should see an error.

[zonca]

here is the error I get:

(.venv) exouser@cdms24:~/kaitai_struct_awkward_runtime$ ./tests/debug_tests
terminate called after throwing an instance of 'std::__ios_failure'
  what():  basic_ios::clear: iostream error
Aborted (core dumped)

[dchoi]

Yes, I reproduced the error.

=========================== no tests ran in 0.00s ===========================
ERROR: file or directory not found: tests/test_soudan.py

make: *** [Makefile:19: compile_test] Error 4
terminate called after throwing an instance of 'std::__ios_failure'
what(): basic_ios::clear: iostream error
Aborted (core dumped)

[zonca]

@dchoi good, now you can start trying to understand where that is coming from, above in this PR I already had a possible source.

[dchoi]

I have so far traced where this crashes on void soudan_t::soudan_history_buffer_t::_read().
there is 2nd for loop including time_n_minus_veto_mask_builder.append. The loop needs 55 count of l_time_n_minus_veto_mask but crashes around at 27th count.

[zonca]

Thank you. Can you correlate this back to the Kaitai file?