Known issues

A known issue is a behavior of PowderLine itself that is understood and recorded: a limit it accepts, a failure route it documents, or a problem it has resolved. Each has a permanent ID, KI-NN, that the code, messages and the changelog cite. An ID is never reused, so a withdrawn or resolved issue stays listed.

What the engines do on their own, and what PowderLine does about it, is on the Engines pages, under EB-NN IDs. Every ID is listed in the ID index.

Status	Meaning
open	Known, and not yet addressed.
accepted	Known, and deliberately not prevented. The entry says what to do.
watch	A quirk to keep in mind. No action planned.
resolved	Addressed in the current release.
withdrawn	Not a defect.

Severity is the impact if you meet the issue: critical (silent wrong or empty output, or data loss), major (breaks a real workflow), minor (works, but fragile or wrong in edge cases) or nit (cleanup).

Open

KI-19 · The GSAS-II server keeps running until it is stopped

open · minor · GSAS-II server

What happens: A gsasii.* run in the default auto mode starts the GSAS-II server in the background if none is running. The server has no idle timeout. It keeps GSAS-II loaded in memory until you stop it or the computer restarts. If its state directory is removed at logout, the server keeps running unseen (KI-11), and the next login starts another one.

What to do: Stop the server when you finish a session, before you log out: pixi run -e gsasii gsas-server stop. On a shared workstation where no one will stop it, set POWDERLINE_NO_SERVER=1 so runs go in-process. See Run at a beamline.

KI-20 · The GSAS-II server’s state directory must be on this computer’s own disk

open · minor · GSAS-II server

What happens: The server’s state directory holds server.lock, server.pid and server.json. It is $XDG_RUNTIME_DIR/powderline, or <temp folder>/powderline-<uid>, because the server belongs to one computer. If TMPDIR points into a network folder shared by several computers, such as a network home directory, those computers share the files. gsas-server stop on one computer could then read the process ID of a server on another and signal an unrelated process of yours. This is inferred from the code; it has not been reproduced.

What to do: Keep TMPDIR on this computer’s local disk. If PowderLine refuses the state directory because the temp folder is not private, point TMPDIR or XDG_RUNTIME_DIR at a private folder on the local disk, not in a network home directory.

KI-21 · gsas-server stop can read a leftover process ID in a narrow race

open · minor · GSAS-II server

What happens: gsas-server stop treats the server as running while anything holds the lock on server.lock. Another client checks for a server by taking that lock for a moment. If a server died without removing server.pid, and a client’s check coincides with stop, stop signals the process ID in that leftover file. The ID may by then belong to another of your processes. The window is a fraction of a second.

What to do: Run pixi run -e gsasii gsas-server status before stop when a server may have crashed. If status reports no server, there is nothing to stop.

Accepted

KI-06 · GSAS-II recipes have no parameter bounds

accepted · minor · gsasii

What happens: GSAS-II enforces a limit by resetting an out-of-range value to the limit after a refine, and freezing it for the next one (EB-30). Coordinate limits are set on Ax, Ay, Az, while GSAS-II varies dAx, dAy, dAz. Cell limits map exactly onto direct-cell boxes for only four of the seven crystal systems (EB-31). gsasii.* recipes therefore expose no bounds: a 4-element parameter list is a validation error.

What to do: Write [value, flag] in gsasii.* recipes. topas.* and easydiffraction.* recipes have bounds, each with its engine’s semantics. Bounds may come in a later gsasii schema version.

KI-11 · A server whose state directory is deleted keeps running unseen

accepted · minor · GSAS-II server

What happens: The GSAS-II server keeps its state in a per-user directory: server.lock, server.pid, and server.json with the port and token. “Running” means holding the kernel lock on server.lock, and clients use only the endpoint in server.json. If that directory is deleted while a server runs, for example $XDG_RUNTIME_DIR removed at logout or a temp-directory cleaner, the server keeps running unused. Clients cannot find it, and gsas-server status and stop cannot see it. A running job’s scratch files, under the same directory, are lost too.

What to do: End the server by hand. On Linux and macOS, list your server processes with ps -u "$(id -un)" -o pid=,args= | grep -E "python[^ ]* .*gsasii[/.]server", check that each path is this checkout’s, and end each one with kill <PID>. On Windows, end the Python process whose command line ends in gsasii\server.py start or -m powderline.gateways.gsasii.server start. Don’t use pkill -f: its pattern also matches an editor open on server.py and servers of other checkouts.

KI-15 · Four example references refine unphysical values, so their output recipes are invalid

accepted · minor · examples

What happens: Four committed GSAS-II references end on values the schemas refuse. example_DRX_33 refines a Li4MgWO6 crystallite size of about −1355 µm. example_DRX_33_anisoADP refines a size of about −9.7 µm. example_DRX_33_atomrefine refines a Li occupancy of about −0.35 and a size of about −8 µm. example_LaB6_singlepeakfit refines its background peak’s σ² to about −2700 centideg², below GSAS-II’s silent floor (EB-35). These runs return output_recipe_valid: false, with the warning output_recipe_not_valid naming the value. The easydiffraction leg of example_LaB6_ionic is in the same position: its fit refines CrysPy’s Lorentzian X negative (EB-87).

What to do: Read these as teaching examples of ill-conditioned refinements: the SVD warnings, the railed sizes. example_DRX_33_strainonly is the physical DRX_33 variant. Each example’s description gives the result of a physical re-posing where one exists.

KI-17 · A split atom’s occupancy is not checked against its coinciding images

accepted · minor · core

What happens: An atom placed off a special position to model disorder has k symmetry images where the ordered atom had one. k is the general multiplicity divided by the special one. Unless its occupancy is divided by k, the site holds k atoms. PowderLine checks the position: no symmetry image of the atom may lie 5e-6 to 2e-3 from it. It does not check the occupancy, because a full occupancy is also a legitimate model: a genuinely general site.

What to do: Divide the occupancy by k yourself. See Model disorder near special positions.

KI-18 · A coordinate that refines close to a special position is reported only through the output recipe

accepted · minor · core

What happens: Validation refuses an atom stated near a special position without being on it: one with a symmetry image 5e-6 to 2e-3 (fractional) away. During a refinement, no engine moves a coordinate back onto a special position. GSAS-II never snaps, easydiffraction detects Wyckoff positions only when the structure is built (EB-74), and TOPAS compares exactly. So a split atom can refine into that band. The result is still returned, because its numbers are what the engine computed. Its output recipe fails validation, and the warning output_recipe_not_valid names the coordinate, so a chained next step stops there.

What to do: State the atom on the special position, or restart it further off. See Model disorder near special positions.

Resolved

KI-01 · A cell that breaks its space group is refused

resolved · critical · core

What happens: GSAS-II uses a fixed cell as given, even when it breaks the space group (EB-06). A cubic phase with a ≠ b ≠ c would give wrong peak positions and a refinement that reports success. Core refuses such a cell in every engine schema. Tied lengths and angles must equal the first member, and fixed angles must be exact, within 1e-9. The error gives the value to write.

What to do: Write the value the error names. PowderLine has no switch that accepts a symmetry-breaking cell.

KI-02 · A partly refined GSAS-II cell group is refused

resolved · minor · gsasii

What happens: GSAS-II refines a cell through its reciprocal-metric terms. Holding one of them equals holding a direct-cell parameter only for orthogonal cells. In a b-unique monoclinic cell a, c and β are coupled. In a triclinic cell, and on rhombohedral axes, all six are. A gsasii.* recipe that refines a strict subset of such a group, or of a symmetry tie group, is a validation error at the offending field. A flag is never silently overridden.

What to do: Refine the whole group or none of it. engine_details.parameters_requested and parameters_varied show what GSAS-II varied.

KI-03 · Site symmetry and multiplicity are derived and checked

resolved · major · core, gsasii

What happens: Core derives each atom’s site symmetry, multiplicity and tie groups with gemmi, without an engine. It cross-checks a stated Multiplicity. After phase setup, the gsasii gateway compares GSAS-II’s reading of every site with core’s. It stops with an error when GSAS-II misreads a site or cannot name it (EB-40, EB-05). Nothing is swallowed.

What to do: Site symmetry is derived, not stated. If a GSAS-II run stops with unusable_site, write the equivalent position the error names.

KI-04 · Every result carries an output recipe and per-parameter dispositions

resolved · major · core

What happens: Every result carries output_recipe: the resolved recipe, with the refined values written back at their recipe paths. It also carries parameter_dispositions, one row per refinable value, with its ESD and at_limit. The disposition is varied, held_by_user, held_by_symmetry, requested_not_varied or default_applied. When a refined value breaks a schema rule, the output recipe is still returned, with output_recipe_valid: false and the warning output_recipe_not_valid.

What to do: To chain runs, swap only the xrd_data block into each step’s output recipe. example_LaB6_temperature_series does this with GSAS-II and with easydiffraction. See Run a sequential refinement.

KI-05 · GSAS-II refinement failures raise, with the console text attached

resolved · major · gsasii

What happens: GSAS-II’s refine() does not raise on failure. Its notices go to the console, or into the project. The gsasii gateway reads the stored messages into gsasii_refinement_message warnings (EB-32). It reads the convergence flag into converged, with gsasii_fit_not_converged. A non-finite pattern or an aborted refinement raises EngineExecutionError, reason diverged. The other reasons are unusable_site, peak_fit_failed and engine_crashed. The gateway also keeps the last 65,536 characters of GSAS-II’s Python console output for each run.

What to do: After a failure, read failure.console_tail, in the exception’s .result or in failure.json. The CLI prints its last lines after “Refinement failed”. A verbose run that succeeded carries the tail under engine_details. Output from compiled code is not captured.

KI-07 · The space-group setting is stated, never inferred

resolved · critical · core, gsasii

What happens: R -3 c on hexagonal axes and R -3 c R on rhombohedral axes imply different cells. GSAS-II reads a two-origin group in origin choice 2, so origin-1 coordinates would run on the wrong structure without a message. Core requires gemmi’s canonical extended Hermann–Mauguin name, which states the setting: :1 or :2, :H or :R, and the monoclinic axis. Any other spelling is an error naming the canonical form. A bare two-origin or rhombohedral symbol lists both choices. The gsasii gateway refuses origin choice 1 and 9 further settings (EB-03, EB-41).

What to do: Write the canonical name. For a setting the gsasii gateway refuses, transform the structure to a standard setting.

KI-08 · The docs build treats every warning as an error

resolved · nit · docs build

What happens: pixi run docs runs sphinx-build -W --keep-going with nitpicky = True. Targets that are documented nowhere Sphinx can link to are listed in nitpick_ignore in docs/conf.py.

What to do: Keep the build warning-free. Add a target to nitpick_ignore only when it has no documentation Sphinx can link to.

KI-10 · Stopping an unresponsive GSAS-II server escalates to a forced kill on every platform

resolved · minor · GSAS-II server

What happens: When the server has not exited 5 s after a stop request, stop escalates to a forced kill. On Windows, where SIGKILL does not exist, it uses SIGTERM, which Python maps to TerminateProcess, a hard kill. Unit tests drive the escalation path with a mocked process. The Windows branch has not been run against a live, unresponsive server.

What to do: Nothing in normal use. If stop fails on Windows, end the server process by hand.

KI-12 · The GSAS-II server returns output files inside its response

resolved · major · GSAS-II server

What happens: The server runs each job in a private scratch directory under its per-user state directory. It returns every PowderLine output file, base64-encoded, inside the signed response. The client writes the files into its own output directory and lists them in output_files. No shared filesystem is needed, so a server on another node or in a container works like a local one. The response is a versioned envelope.

What to do: Nothing.

KI-13 · Engine dispatch depends on install-time entry-point metadata

resolved · minor · installation

What happens: powderline.run() and powderline.validate() find every gateway through the powderline.gateways entry points of the installed distribution. That is the only discovery path. If an environment’s editable install is stale or half-installed, or PowderLine is imported from source with PYTHONPATH and no installed distribution, every run fails with GatewayNotInstalledError. The message names the fix.

What to do: Run pixi run powderline --doctor. It lists the gateways the registry finds and each engine’s version against its requirement. It exits non-zero when something is missing, and names the repair to run. Contributors who edit the package’s entry points: see Troubleshooting for contributors.

KI-14 · The GSAS-II server is private to the user who started it

resolved · critical · GSAS-II server

What happens: Each user gets their own server. Its lock, PID, log and endpoint live in a private per-user state directory, with mode 0600 files on POSIX. The server listens on 127.0.0.1 on an ephemeral port. Every request and every response is signed with a per-start token that never crosses the wire. Unsigned, wrongly signed, stale or replayed requests are refused. A kernel-held lock on server.lock allows one server per user. The request carries no output directory: files travel back inside the response (KI-12).

What to do: Nothing in normal use. To keep any server from starting, set POWDERLINE_NO_SERVER=1. Then auto runs in-process, server mode and --use-server fail, and gsas-server start refuses. Operation is described in Run at a beamline.

KI-16 · TOPAS execution is verified on TOPAS 6

resolved · major · topas

What happens: The topas_exec tests run tc.exe against the committed goldens under tests/data/topas/native/golden/6/. On the release’s code they reproduced all seven golden fixtures file for file through powderline.run(). The ionic example’s La3+/La intensity ratios agree with GSAS-II’s within 0.069 %. The textured example recovers the March–Dollase ratio as 0.5982(14), against the programmed 0.6. Without tc.exe, a run is generate-only, with the goldens as the contract.

What to do: On a TOPAS machine, run pixi run test-topas with POWDERLINE_TOPAS_DIR and POWDERLINE_TOPAS_VERSION set. TOPAS 7 is not supported: it needs its own goldens and the same tests.

Withdrawn

KI-09 · Withdrawn

withdrawn

What happens: The reported behavior was intentional, not a defect.

What to do: Nothing. The id is kept so it is never reused.