pyz1

English | 中文

pyz1 is a local Python implementation path for reproducing the public Z1+ workflow. It is a clean-room Python package for parsing Z1+/LAMMPS-style polymer inputs, writing Z1+ compatible outputs, computing summary/Ne values, running native PPA/PPA+ slices, and building a native geometrical Z1 reducer without using the Linux Z1+.ex binary at runtime.

Quickstart

Local development uses the pyz1 micromamba environment. On this macOS host, keep the file-descriptor limit finite for micromamba:

ulimit -n 1000000; micromamba run -n pyz1 python -m pytest -q
ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 --help

Run the native default reducer on a Z1 input:

ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 config.Z1

Run SP+ pairing mode:

ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 -SP+ config.Z1

Run selfZ execution mode:

ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 -selfZ config.Z1

Write a default/SP+/selfZ benchmark regression report:

ulimit -n 1000000; micromamba run -n pyz1 pyz1-benchmark-regression \
  --source-dir /Users/jiaxm/Contents/CodexProjects/source_code/Z1+ \
  --oracle-root tests/fixtures/z1plus_oracle/corpus-default-spplus-selfz-20260703 \
  --report-path pyz1-benchmark-regression.md

By default this discovers every benchmark-* directory under the oracle root. Pass --benchmark-id repeatedly to restrict the report to a smaller slice. Use --max-node-count to tune the benchmark skip guard, and --trace-diagnostics-max-node-count to disable expensive trace diagnostics for larger runnable cases while still reporting summary and geometry deltas.

Run native PPA/PPA+ modes:

ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 -PPA config.Z1
ulimit -n 1000000; micromamba run -n pyz1 python -m pyz1 -PPA+ config.Z1

Write a PPA/PPA+ oracle coordinate fixture-health report:

ulimit -n 1000000; micromamba run -n pyz1 pyz1-ppa-oracle-coordinates \
  --oracle-root tests/fixtures/z1plus_oracle/corpus-ppa-ppaplus-20260703 \
  --report-path ppa-oracle-coordinate-report.md

By default this discovers every benchmark-* directory under the oracle root. Pass --benchmark-id repeatedly to restrict the report to a smaller slice.

Write a native PPA/PPA+ summary regression report:

ulimit -n 1000000; micromamba run -n pyz1 pyz1-ppa-regression \
  --source-dir /Users/jiaxm/Contents/CodexProjects/source_code/Z1+ \
  --oracle-root tests/fixtures/z1plus_oracle/corpus-ppa-ppaplus-20260703 \
  --report-path pyz1-ppa-regression.md \
  --max-node-count 1000

By default this discovers every benchmark-* directory under the oracle root and runs both PPA modes. Pass --benchmark-id repeatedly to restrict the report to a smaller slice. --max-node-count guards expensive native PPA runtime cases and records oversized cases as known-invalid.

Run the package-level integration smoke:

ulimit -n 1000000; micromamba run -n pyz1 pytest -q tests/test_package_integration_smoke.py

That smoke drives the installed package surface through python -m pyz1 for default, SP+, PPA, and PPA+ modes and checks the mode-specific output files.

Outputs

The package has parser/writer coverage for:

• Z1+summary.dat
• Z1+SP.dat with optional SP+ other-chain other-node columns
• Z1+initconfig.dat
• Ree_values.dat
• Lpp_values.dat
• N_values.dat
• Z_values.dat
• PPA.dat
• PPA+.dat
• PPA-summary.dat
• PPA+summary.dat

Default and SP+ CLI modes currently write Z1+SP.dat, Z1+summary.dat, and the Ree/Lpp/N/Z_values.dat files. PPA/PPA+ modes write their corresponding coordinate and summary/value outputs.

Benchmark Status

The original Linux Z1+.ex binary is an oracle for fixtures only; it is not a runtime dependency of the Python package.

Current regression evidence is written to:

.omo/evidence/pyz1-benchmark-regression.md

That report classifies each public benchmark/mode as passed, mismatch, or known-invalid. The current clean-room reducer is not yet numerically equivalent to Z1+: benchmark-04 default/SP+/selfZ is reported as passed, benchmark-01, benchmark-02, benchmark-03, and benchmark-05 remain mismatch, and larger benchmark cases are performance-skipped by a transparent node_count guard until the reducer gets neighbor-list style acceleration.

References

The upstream Z1+ source asks users to cite the following publications when using Z1+ results:

• M. Kroger, "Shortest multiple disconnected path for the analysis of entanglements in two- and three-dimensional polymeric systems," Comput. Phys. Commun. 168, 209-232 (2005). DOI: 10.1016/j.cpc.2005.01.020
• S. Shanbhag and M. Kroger, "Primitive path networks generated by annealing and geometrical methods: Insights into differences," Macromolecules 40, 2897-2903 (2007). DOI: 10.1021/ma062457k
• R. S. Hoy, K. Foteinopoulou, and M. Kroger, "Topological analysis of polymeric melts: Chain-length effects and fast-converging estimators for entanglement length," Phys. Rev. E 80, 031803 (2009). DOI: 10.1103/PhysRevE.80.031803
• N. C. Karayiannis and M. Kroger, "Combined molecular algorithms for the generation, equilibration and topological analysis of entangled polymers: Methodology and performance," Int. J. Mol. Sci. 10, 5054-5089 (2009). DOI: 10.3390/ijms10115054
• "The Z1+ package: Shortest multiple disconnected path for the analysis of entanglements in macromolecular systems," Comput. Phys. Commun. (2022), listed in the upstream Z1+ README/source as submitted/in press.

Limitations

• The missing public module-Z1.f90 source means the default geometrical Z1 reducer is clean-room, not a Fortran translation.
• Default/SP+ reducer parity is not complete. Do not treat current outputs as a drop-in replacement for Z1+ scientific production runs.
• PPA/PPA+ has native Python execution and oracle-backed summary slices, but full benchmark-level runtime parity remains open.
• -selfZ / -0 has a package execution surface, but selfZ scientific parity follows the same clean-room reducer limitations as the default/SP+ path and must be judged through the benchmark regression report.
• The first implementation intentionally avoids GPU, CUDA, CuPy, PyTorch, Numba, and accelerator-specific dependencies.

See docs/pyz1-contract.md for the implementation contract and parity policy, docs/evidence-ledger.md for the current test/evidence index, and docs/completion-audit.md for the current completion verdict.