pyatsas 0.1.0

Python wrappers and input builders for ATSAS command-line tools.

pyatsas

pyatsas provides lightweight Python wrappers around ATSAS command-line tools and small helpers for preparing the input files used by dialog-driven ATSAS programs.

This package is an independent Python wrapper for ATSAS command-line tools. ATSAS itself is not distributed with this package and must be installed separately. pyatsas does not reimplement ATSAS algorithms; it focuses on making ATSAS calls reproducible from Python code, notebooks, and automated workflows.

What Is Included

• Command wrappers for ATSAS programs such as autorg, crysol, dammin, dammif, gnom, bunch, coral, ranch, gajoe, monsa, bodies, ffmaker, and related utilities.
• Input builders for interactive ATSAS tools, including MONSA, RANCH/GAJOE, BUNCH, and CORAL.
• Small data-reading helpers for common SAXS output files.
• Unit tests that mock ATSAS execution, so the default test suite can run without ATSAS installed.

ATSAS Dependency

pyatsas does not bundle ATSAS. Importing pyatsas does not require ATSAS, but calling a wrapper requires the corresponding ATSAS executable to be available in the process environment.

Wrappers call executables by name, for example autorg, crysol, or coral. This means the ATSAS binary directory must be on PATH. If an executable is missing, pyatsas raises AtsasExecutableNotFoundError with the missing program name and a short troubleshooting message.

Useful ATSAS links:

• ATSAS download and license information: https://www.biosaxs.com/download
• ATSAS software overview: https://biosaxs.com/software.html
• EMBL Hamburg ATSAS page for older academic ATSAS 3.x information: https://www.embl-hamburg.de/biosaxs/download.html

Academic users should follow the registration and licensing instructions on the ATSAS download page. Commercial users should follow the BIOSAXS licensing instructions.

Troubleshooting Missing Executables

Check that ATSAS works from the same shell or environment where Python runs:

autorg --help

On Windows, add the ATSAS installation directory containing the .exe files to PATH, then restart the terminal, IDE, notebook kernel, or Python session.

You can also check availability from Python:

from pyatsas import require_atsas_executable

require_atsas_executable("autorg")

Installation

For development from a local checkout:

python -m pip install -e .

The Python package depends on numpy and pandas. ATSAS itself must be installed separately.

Basic Usage

Run a command-style ATSAS wrapper:

from pyatsas import autorg

result = autorg("sample.dat")
print(result["result"])

Build an answer script for an interactive program:

from pyatsas import build_coral_answers_text, write_coral_script_file

script = build_coral_answers_text(
    project_name="model",
    description="CORAL run from Python",
    config_token="config",
    use_config=True,
    datafile="sample.dat",
)
write_coral_script_file("coral.stdin", text=script)

Run an interactive wrapper by passing a prepared script:

from pyatsas import coral

result = coral(script_path="coral.stdin", cwd="run")
print(result["stdout"])

More examples are collected in pyatsas/IO_BUILDERS_USAGE.md.

Tests

The default test suite does not require ATSAS:

pytest

ATSAS integration tests are marked with atsas and are skipped by default. Run them explicitly only in an environment where ATSAS executables are available on PATH:

pytest -m atsas

Development Notes

• Wrapper functions generally return a dictionary with the tool name, command, return code, stdout, stderr, outputs, and working directory.
• Non-zero ATSAS exits raise subprocess.CalledProcessError.
• Missing input files raise FileNotFoundError.
• Missing ATSAS executables raise AtsasExecutableNotFoundError.
• Dialog/input builders return plain text so generated scripts can be inspected, tested, and version-controlled.

License

pyatsas is distributed under the MIT License. ATSAS is a separate software package with its own license and must be obtained from the official ATSAS distribution channels.