mvnayagam/pypsc

Purpose and execution model

pypsc is a Python scientific-computing library for recovering 1D-projected independent-scatterer coordinates from diffraction structure-factor amplitudes or intensities. It replaces Fourier inversion with Parameter Space Concept (PSC): represent each reflection as a piecewise analytic isosurface, linearize it into feasible polytopes, then intersect constraints to retain all compatible structures. There is no standalone application/server entry point; notebooks are the primary interactive entry points: examples/ex01-EPA/EPA.ipynb, examples/ex02-NEPA/NEPA.ipynb, and examples/ex03-MCEPA/mcsolver.ipynb.

Core diffraction and parameter-space model

Low-level PSC mathematics is organized in lib/. Scattering factors and reciprocal/parameter-space calculations are provided by lib/getscatteringfactor.py and lib/gspacer.py; origin handling is separated in lib/choiceoforigin.py. These inputs define reflection-specific constraints over fractional atomic-coordinate parameter space, rather than reconstructing density from a Fourier map.

Linearization pipeline

lib/linearizer.py converts amplitude/intensity isosurfaces into linearized representations suitable for geometric solving. lib/checklinearizer.py validates that approximation, creating an explicit numerical-quality boundary before constraints are used downstream. The README’s tolerance warning is architecturally important: the external Python polytope package underlies feasible-region operations and must be configured with tighter ABS_TOL for fractional-coordinate precision.

Constraint intersection and solution lifecycle

The main deterministic solver is lib/pscsolver.py. It combines reflection constraints through geometric intersection (lib/intersector.py) and subdivision/tessellation (lib/tessellator.py) to derive candidate solution regions. Candidate regions are then consolidated and filtered through lib/solutionmerger.py and lib/solutionselector.py. This establishes the main control flow: diffraction observations → linearized repeated constraints → polytope intersections → merged/selected structural solutions.

Persistence and downstream analysis

Solutions and intermediate PSC/polytope results are persisted as HDF5, evidenced by the solver outputs under examples/ex01-EPA/ and examples/ex02-NEPA/. lib/solutionIO.py is the write/read boundary, while lib/solutionreader.py provides result consumption. HDF5 files allow expensive solver runs to be inspected and plotted later rather than requiring an in-memory interactive session.

Monte Carlo and dimensional extensions

lib/mcsolver.py orchestrates Monte Carlo-oriented solving, with example outputs collected in examples/ex03-MCEPA/temp/. The lib/2DandMC/ subtree contains specialized workflows for 2D parameter spaces and Monte Carlo variants: lib/2DandMC/MCin2DPS_EPA.py, lib/2DandMC/MCin2DPS_nEPA.py, and lib/2DandMC/MCinNDPS_EPA.py. These branch from the deterministic PSC pipeline to simulate or explore random structures while retaining EPA/nEPA-specific handling.

User-facing visualization and support layer

Notebooks compose library routines with analysis/plotting utilities, including tools/plot3DMCresults.py, tools/x3Dplot.py, and utils/plothdf.py. Logging is centralized in config/logconfig.py and utils/logger.py. The repository’s material runtime is Python, packaged through pyproject.toml; principal external dependencies include the polytope geometry package and an HDF5-capable Python stack implied by persisted .h5 results.