ddscatcli 1.0.4

CLI utility to edit and run a ddscat.par file for DDSCAT

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.).