File size: 3,347 Bytes
bc2957c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | # Usage
Run from a calculation directory containing:
- `energy_vs_q.dat`
- `elk.tmp`
- optionally `jfile`
Install in editable mode before running the examples:
```bash
pip install -e /path/to/FourJ[dashboard]
```
## Full Fourier Transform
```bash
fourj \
--energy energy_vs_q.dat \
--elk elk.tmp \
--vectors jfile \
--theta 90 \
--symmetry spglib \
--output-prefix fourj
```
## Real-Space Vector Selection
`J(R)` vectors are integer direct-lattice coordinates. In output tables these
appear as `R1 R2 R3`, meaning
```text
R_cart = R1*a1 + R2*a2 + R3*a3
```
where `a1`, `a2`, and `a3` are the direct lattice vectors parsed from the Elk
input. Selection priority is:
1. explicit `--vectors` file, or `./jfile` if present;
2. `--rmax`, which generates all integer direct-lattice translations within the
real-space cutoff in Angstrom;
3. otherwise, a centered integer `R` grid inferred from the nested q-mesh
dimensions, limited to half of the maximum inferred real-space distance.
This keeps the default transform away from the longest mesh-boundary
vectors while still requiring no manual cutoff.
## Seekpath Plot with Dense FT Spectrum
```bash
fourj \
--energy energy_vs_q.dat \
--elk elk.tmp \
--vectors jfile \
--theta 90 \
--symmetry spglib \
--plot-path \
--plot-lswt \
--lswt-dense-path
```
## Two-Shell LSQ Fit
```bash
fourj \
--energy energy_vs_q.dat \
--elk elk.tmp \
--vectors jfile \
--theta 90 \
--symmetry spglib \
--fit-lsq \
--fit-num-shells 2 \
--plot-path \
--plot-lswt \
--lswt-dense-path
```
## Interactive Dashboard
Install the optional dashboard dependencies:
```bash
pip install -e /path/to/FourJ[dashboard]
```
Then run:
```bash
fourj-dashboard
```
The dashboard opens at `http://127.0.0.1:8050`. Upload an Elk input or
`elk.tmp`, upload `energy_vs_q.dat`, and optionally upload a `jfile`. The app
runs the same `FrozenMagnonWorkflow` as the CLI and shows the reciprocal
q-point cloud, full input `E(q)`, Seekpath DFT/FT/LSQ comparisons, and
real-space `J(R)`. It can also download an UppASD-style exchange file with
columns `iatom jatom r_x r_y r_z Jij |rij|`; `Jij` is in mRy and `|rij|` is in
Angstrom. The dashboard q-point markers are colored by
`E(q)-E0` in mRy, and the status panel reports available Bravais and
space-group metadata from Seekpath/spglib.
You can also launch it preloaded from CLI file paths and settings:
```bash
fourj --energy energy_vs_q.dat --elk elk.tmp --symmetry spglib --gui
```
## Programmatic API
```python
from pathlib import Path
from fourj import FrozenMagnonWorkflow, WorkflowConfig
workflow = FrozenMagnonWorkflow(
WorkflowConfig(
energy_path=Path("energy_vs_q.dat"),
elk_path=Path("elk.tmp"),
vectors_path=Path("jfile"),
theta=90.0,
symmetry="spglib",
)
)
result = workflow.run_transform()
workflow.write_transform_outputs()
lsq = workflow.fit_lsq(max_shells=2)
workflow.write_lsq_outputs()
```
## Hosting
The repository includes `app.py` and a `Dockerfile` for hosting the dashboard.
For Hugging Face Spaces, create a Docker Space and push the repository; the
container listens on port `7860`. Generic Python hosts can run
`gunicorn app:server`, while command-based hosts can run `fourj-dashboard` with
`HOST=0.0.0.0` and their provided `PORT`.
|