ddscatcli

This script is a command-line utility to edit and run a ddscat.par file for DDSCAT in a reproducible and automated way.

It allows you to:

• Modify parameters inside a single ddscat.par configuration file (shape, solver, FFT method, dielectric files, wavelength, etc.).
• Run DDSCAT automatically — serial, MPI, or OpenMP.
• Create timestamped backups of the original ddscat.par file.
• Uses environment variables for configuration (no code editing).

Configuration

ddscatcli resolves ddscat.par in this order:

1. $DDSCAT_PAR (absolute path recommended; relative paths are interpreted relative to your current working directory)
2. ddscat.par (current working directory)

ddscatcli resolves the DDSCAT executable in this order:

1. $DDSCAT_EXE (absolute path recommended; relative paths are interpreted relative to your current working directory)
2. ddscat (current working directory)
3. ddscat found on your PATH

Example:

export DDSCAT_PAR=/abs/path/to/ddscat.par
export DDSCAT_EXE=/abs/path/to/ddscat

Postprocessing (ddpostprocess)

ddscatcli can optionally run ddpostprocess (from DDSCAT) after a simulation, or independently using -post flag.

Environment variables

• DDPOST_EXE: path to the ddpostprocess executable (absolute recommended)
• DDPOST_PAR: path to ddpostprocess.par (absolute recommended)

If not set, ddscatcli looks in the current working directory for:

• ddpostprocess
• ddpostprocess.par

Installation

Install from PyPI:

pip install ddscatcli

This installs the ddscatcli command globally. If you prefer to keep it isolated in a virtual environment:

python -m venv .venv
source .venv/bin/activate   # on Linux/macOS
# .venv\Scripts\activate    # on Windows

pip install ddscatcli

Requirements

• Python >= 3.10
• Standard library only

Usage

1. Get help and options:

   ddscatcli -h
   

2. List available shapes:

   ddscatcli -CSHAPE -h
   

3. Run modes:

   • -dry-run → preview the edits only (no file modification).
   • (no flag) → apply edits to ddscat.par.
   • -run → apply edits and automatically run DDSCAT.

4. Parallel options:

   • -omp-threads N → set the number of OpenMP threads.
   • -mpi [launcher] -np N → run DDSCAT with MPI (e.g. mpirun, mpiexec, srun).

Examples

Preview edits without modifying:

ddscatcli -CSHAPE ANIRCTNGL -dry-run

Change the shape and run immediately:

ddscatcli -CSHAPE ELLIPSOID -SHPAR "16 8 4" -run

Set OpenMP threads:

ddscatcli -omp-threads 16 -run

You can repeat -DIEL once per material:

ddscatcli -NCOMP 3 -DIEL diel1.txt -DIEL diel2.txt -DIEL diel3.txt

Or provide them in a single flag:

ddscatcli -NCOMP 3 --diels diel1.txt diel2.txt diel3.txt

Note: if -NCOMP is provided, the number of dielectric entries must match NCOMP exactly.

Use from Python

ddscatcli exposes a run function.

import os
import ddscatcli

os.environ["DDSCAT_PAR"] = "/abs/path/to/ddscat.par"
os.environ["DDSCAT_EXE"] = "/abs/path/to/ddscat"

ddscatcli.run(["-dry-run", "-CSHAPE", "ELLIPSOID"])

Backups

Every modification automatically creates a timestamped backup:

ddscat.par.bak.YYYYMMDD-HHMMSS

Notes

• Each parameter is matched using its identifying keyword in the ddscat.par file.
• Supports dielectric and shape overrides via -DIEL, -NCOMP, -SHPAR, etc.
• DDSCAT must be compiled and installed separately — this tool just wraps it.

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). You are free to use, modify, and share it under the same license.

Citation

If you use ddscatcli, please cite:

Clément Argentin, ddscatcli (2025).
DOI: 10.5281/zenodo.17493074

You can click the “Cite this repository” button on the right-hand side of the GitHub page for citation formats (BibTeX, APA, etc.).