Migration summary for pMoleculeScripts CMake/Python3 port
=========================================================

Scope
-----
This document records the current pMoleculeScripts migration state in the new
CMake/Python3 build layout and the additional fixes required to make import
tests pass cleanly in the conda env hpc environment.

Environment used for validation
-------------------------------
- Python interpreter: /opt/miniconda3/envs/hpc/bin/python3.10
- Build/test environment: conda env hpc

Package role
------------
pMoleculeScripts is a high-level workflow package. It does not define low-level
C extensions itself. Instead, it provides molecular modeling utility scripts
that depend on pCore, pGraph, pMolecule and pBabel.

Current build layout
--------------------
1. pMoleculeScripts-2.0.0/CMakeLists.txt
   - Copies pMoleculeScripts Python files into build/python/pMoleculeScripts.
   - Registers two import smoke tests:
     - test_import_pmoleculescripts
     - test_import_all_pmoleculescripts_modules

Files modified
--------------
1. pMoleculeScripts-2.0.0/pMoleculeScripts/ParallelizationOptions.py
   - Changed MPI2 availability detection so that the code checks whether
     mpi4py is installed without importing it eagerly.
   - This avoids import-time MPI initialization side effects during ordinary
     package import.

2. pMoleculeScripts-2.0.0/pMoleculeScripts/SGOFProcessPool.py
   - Deferred the actual mpi4py import so it occurs only when the MPI2 process
     pool is initialized or finalized.
   - Replaced the process script lookup based on the environment variable
     PDYNAMO_PMOLECULESCRIPTS with a path derived from __file__.
   - This makes the MPI2 helper script location consistent with the current
     CMake build/python package layout.

Why these changes were needed
-----------------------------
The original code assumed a legacy environment layout in which:
- mpi4py could be imported safely during package import, and
- PDYNAMO_PMOLECULESCRIPTS was already defined and pointed to a package root.

In the current build layout this caused two problems during:
    import pMoleculeScripts

1. Import-time MPI side effects
   - mpi4py/OpenMPI attempted to initialize low-level networking during import.
   - In restricted environments this produced runtime messages such as:
     bind() failed: Operation not permitted

2. Import-time environment variable failure
   - SGOFProcessPool.py constructed:
     os.path.join(os.getenv("PDYNAMO_PMOLECULESCRIPTS"), "pMoleculeScripts", "SGOFProcessMPI2Script.py")
   - If PDYNAMO_PMOLECULESCRIPTS was not set, import failed with:
     TypeError: expected str, bytes or os.PathLike object, not NoneType

Behavior after the fix
----------------------
- The SGOF functionality is preserved.
- MPI2 support is preserved.
- Normal package import no longer requires:
  - mpi4py to be initialized at import time
  - PDYNAMO_PMOLECULESCRIPTS to be set
- The MPI2 helper script is resolved relative to the installed/copied module
  location, which matches the current build/python package structure.

Important design note
---------------------
SGOF means System Geometry Objective Function.

The SGOF process pool is a parallelization support layer used by higher-level
path optimization workflows such as chain-of-states methods. It should remain
available, but its optional MPI backend should not be forced during ordinary
package import.

Validation performed
--------------------
1. Clean rebuild in current source tree
   - Removed current build directories and regenerated the build using:
     - cmake -S . -B build
     - cmake --build build -j

2. Targeted tests
   - ctest --test-dir build -R test_import_pmoleculescripts --output-on-failure
   - ctest --test-dir build -R test_import_all_pmoleculescripts_modules --output-on-failure

3. Full configured test set
   - ctest --test-dir build --output-on-failure

Final status
------------
- pCore import tests passed
- pGraph import tests passed
- pMolecule import tests passed
- pBabel import tests passed
- pMoleculeScripts import tests passed
- Full configured CTest suite passed: 10/10 tests
