Metadata-Version: 2.4
Name: ddscatcli
Version: 1.0.3
Summary: CLI utility to edit and run a ddscat.par file for DDSCAT
Author-email: Clément Argentin <argentin-clement@outlook.fr>
License-Expression: GPL-3.0
Project-URL: Homepage, https://pypi.org/project/ddscatcli/
Project-URL: Repository, https://github.com/Argencle/ddscatcli
Project-URL: Changelog, https://github.com/Argencle/ddscatcli/blob/main/CHANGELOG.md
Keywords: DDSCAT,DDA,light scattering,cli
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ddscatcli
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17493074.svg)](https://doi.org/10.5281/zenodo.17493074)
[![PyPI](https://img.shields.io/pypi/v/ddscatcli.svg)](https://pypi.org/project/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:

```bash
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:

```bash
pip install ddscatcli
```

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

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

pip install ddscatcli
```

---

## Requirements

* **Python 3.8>=**
* Standard library only 

---

## Usage

1. Get help and options:

   ```bash
   ddscatcli -h
   ```

2. List available shapes:

   ```bash
   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:

```bash
ddscatcli -CSHAPE ANIRCTNGL -dry-run
```

Change the shape and run immediately:

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

Set OpenMP threads:

```bash
ddscatcli -omp-threads 16 -run
```

You can repeat `-DIEL` once per material:
```bash
ddscatcli -NCOMP 3 -DIEL diel1.txt -DIEL diel2.txt -DIEL diel3.txt
```

Or provide them in a single flag:
```bash
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.
```Python
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](https://doi.org/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.).
