Fix the row order of H4 parameter files in MKZ_Param_Multi_Layer

[jsh9]

Fixes #79. One of the four P0 fixes from #114, based on #74's branch (2026-10-10-parametrize-tests).

Problem

H4 parameter files (H4_G_*.txt, H4_x_*.txt) store each layer as gamma_ref, b (always 0), s, beta.

• Reading: MKZ_Param_Multi_Layer() read files and 2D arrays without from_files=True, so every layer got s = 0, beta = the file's s, and Gmax = the file's beta. With s = 0, G/Gmax is a constant (0.5296 for every strain in layer 1 of H4_G_IWTH04.txt), and damping is about 0.
• Writing: save_txt() and get_all_H4_x_params(save_txt=True) wrote gamma_ref, s, beta, Gmax instead of the file layout.

Reading and writing were wrong in the same way, so a file written by the library loaded back unchanged. That is why the existing round-trip tests passed.

Changes

• PySeismoSoil/class_parameters.py:
  • MKZ_Param_Multi_Layer.__init__() reads files and 2D arrays with from_files=True. The class docstring already said the array has the file format; its table now shows the actual rows.
  • New MKZ_Param_Multi_Layer.serialize_to_2D_array() writes the file layout (to_files=True), so save_txt() does too.
  • The file layout has no Gmax: reading sets Gmax = 1.0 and writing drops it. This is now in the docstrings. Gmax does not affect the G/Gmax or damping curves.
• PySeismoSoil/class_curves.py:
  • get_all_H4_x_params() serializes with functools.partial(mkz.serialize_params_to_array, to_files=True).
  • Its docstring said it saves an "HH_x" file of "HH parameters"; it now says H4 and describes the layout.
• PySeismoSoil/helper_site_response.py: the func_serialize docstring of fit_all_damping_curves() mentions to_files=True for H4 files.
• CHANGELOG.md: a "Fixed" entry.
• The example notebooks were re-run (second commit), as CONTRIBUTING.md requires. No notebook loads H4 files or builds MKZ_Param_Multi_Layer from a file or array, so no printed results changed (only timings, folder names, object addresses, and image bytes).

Tests

All of these fail on the old library code (5 failed) and pass with the fix:

• test_mkz_param_multi_layer__test_contents_of_list_elements: the old benchmark [0.000856, 0, 0.88832, 1.7492] encoded s = 0. The test now expects layer 1 of H4_G_IWTH04.txt read in its file layout: gamma_ref=0.00085636, s=0.88832, beta=1.7492, Gmax=1.0.
• test_mkz_param_multi_layer__save_txt_and_load_back (new): serialize_to_2D_array() and the save_txt() file have the rows gamma_ref, 0, s, beta, and both load back with the same parameters (Gmax = 1.0).
• test_construct_curves[from_H4_G_parameters] / [from_H4_x_parameters]: these checked only shapes. They now also compare the values of one layer with the curve from that layer's column read with from_files=True. The HH cases get the same check.
• tests/test_class_curves.py::test_get_all_H4_x_params__saved_file_loads_back (new): the saved file has the file layout and loads back via MKZ_Param_Multi_Layer().

Testing

CI runs only on PRs into main, so it does not run here. These were run locally on Python 3.13:

• python -m pytest tests: 243 passed.
• pre-commit run -a and pydoclint PySeismoSoil: pass.
• tox -e run-notebooks: all 14 notebooks ran without errors.

Notes for review

• Behavior change for files written before this fix: H4 files written by get_all_H4_x_params(save_txt=True) or MKZ_Param_Multi_Layer.save_txt() before this fix are in the old layout (gamma_ref, s, beta, Gmax), and will now load wrongly without an error. Files in the documented H4 layout, such as the ones in tests/files/ and those made by MATLAB SeismoSoil, now load correctly. Should MKZ_Param_Multi_Layer() reject a file whose second row is not 0? That would catch old files, but it is not part of this PR.
• Not changed here: Nonlinear_Simulation accepts MKZ_Param_Multi_Layer for G_param/xi_param according to its docstring. But it writes serialize_to_2D_array() into HH_G.dat/HH_x.dat, which the Fortran kernel reads as 9 HH parameters per layer. So MKZ parameters do not work there with either layout.
• The other P0 fixes (The low-pass, high-pass, band-pass and band-stop filters are not zero-phase, and they ignore padlen #77, amplify_motion() applies the transfer function one frequency bin too high, because _get_freq_interval() starts its frequency array at df instead of 0 #78, Damping_Calibration.get_H4_x_param() returns HH parameters instead of H4 (MKZ) parameters #60 in Fix Damping_Calibration.get_H4_x_param() returning HH parameters #115) are in separate PRs on the same base, and change different library files. All of them re-run the notebooks and add a "Fixed" group to CHANGELOG.md, so whichever merges second will conflict there. To resolve: keep both entries and re-run the notebooks. Fix Damping_Calibration.get_H4_x_param() returning HH parameters #115 (Damping_Calibration.get_H4_x_param() returns HH parameters instead of H4 (MKZ) parameters #60) calls get_all_H4_x_params(), and the two compose in either order.
• Because the base is not main, merging this PR will not close MKZ_Param_Multi_Layer() reads H4 parameter files in the wrong row order, so s is 0 and the G/Gmax curves are flat #79 automatically.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W7fK8T2pPLf3tPCnMCKL1T

---

Generated by Claude Code