fdmnes-util 0.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. fdmnes_util-0.0.0/PKG-INFO +157 -0
  2. fdmnes_util-0.0.0/README.md +141 -0
  3. fdmnes_util-0.0.0/pyproject.toml +28 -0
  4. fdmnes_util-0.0.0/scripts/FDbav2xyz.py +74 -0
  5. fdmnes_util-0.0.0/scripts/FDcif2fdm.py +64 -0
  6. fdmnes_util-0.0.0/scripts/FDclean.py +61 -0
  7. fdmnes_util-0.0.0/scripts/FDconv_e2photoe.py +73 -0
  8. fdmnes_util-0.0.0/scripts/FDfdm2vasp.py +79 -0
  9. fdmnes_util-0.0.0/scripts/FDgetfermi.py +64 -0
  10. fdmnes_util-0.0.0/scripts/FDmakeCconvAllsite.py +59 -0
  11. fdmnes_util-0.0.0/scripts/FDmove.py +62 -0
  12. fdmnes_util-0.0.0/scripts/FDpbd2fdm.py +57 -0
  13. fdmnes_util-0.0.0/scripts/FDplot_LDOS.py +52 -0
  14. fdmnes_util-0.0.0/scripts/FDplot_PDOS.py +62 -0
  15. fdmnes_util-0.0.0/scripts/FDplot_XAS.py +441 -0
  16. fdmnes_util-0.0.0/scripts/FDplot_XAS_LDOS.py +95 -0
  17. fdmnes_util-0.0.0/scripts/FDplot_XASs.py +115 -0
  18. fdmnes_util-0.0.0/scripts/FDvasp2fdm.py +52 -0
  19. fdmnes_util-0.0.0/scripts/FDvasp2fdm_BUG.py +84 -0
  20. fdmnes_util-0.0.0/scripts/FDvasp2fdm_NEW_20151125_BUGversion.py +84 -0
  21. fdmnes_util-0.0.0/scripts/FDxyz2fdm.py +46 -0
  22. fdmnes_util-0.0.0/scripts/fdExp_comp_XAS.py +73 -0
  23. fdmnes_util-0.0.0/scripts/fdLDOS.py +41 -0
  24. fdmnes_util-0.0.0/scripts/fdLDOS0_specified.py +74 -0
  25. fdmnes_util-0.0.0/scripts/fdLDOS_color.py +60 -0
  26. fdmnes_util-0.0.0/scripts/fdLDOSmulti.py +86 -0
  27. fdmnes_util-0.0.0/scripts/fdMulti_2_XAS+LDOS+EXP.py +118 -0
  28. fdmnes_util-0.0.0/scripts/fdMulti_3.py +76 -0
  29. fdmnes_util-0.0.0/scripts/fdPDOS_XAS_av.py +248 -0
  30. fdmnes_util-0.0.0/scripts/fdXAS.py +35 -0
  31. fdmnes_util-0.0.0/scripts/fdXAS_specified.py +68 -0
  32. fdmnes_util-0.0.0/setup.cfg +4 -0
  33. fdmnes_util-0.0.0/src/fdmnes_util/__init__.py +2 -0
  34. fdmnes_util-0.0.0/src/fdmnes_util/analyze_fdm_average.py +122 -0
  35. fdmnes_util-0.0.0/src/fdmnes_util/analyze_fdm_log.py +61 -0
  36. fdmnes_util-0.0.0/src/fdmnes_util/analyze_fdm_xas.py +225 -0
  37. fdmnes_util-0.0.0/src/fdmnes_util/athena_nor.py +129 -0
  38. fdmnes_util-0.0.0/src/fdmnes_util/atomic_symbols.list +103 -0
  39. fdmnes_util-0.0.0/src/fdmnes_util/cif.py +85 -0
  40. fdmnes_util-0.0.0/src/fdmnes_util/cli.py +122 -0
  41. fdmnes_util-0.0.0/src/fdmnes_util/dos_plot_sample.py +277 -0
  42. fdmnes_util-0.0.0/src/fdmnes_util/fdm_bav.py +101 -0
  43. fdmnes_util-0.0.0/src/fdmnes_util/fdm_bav_2016.py +205 -0
  44. fdmnes_util-0.0.0/src/fdmnes_util/fdm_bav_2020.py +208 -0
  45. fdmnes_util-0.0.0/src/fdmnes_util/fdm_conv.py +111 -0
  46. fdmnes_util-0.0.0/src/fdmnes_util/fdm_convolution_inputs.py +80 -0
  47. fdmnes_util-0.0.0/src/fdmnes_util/fdm_inp.py +612 -0
  48. fdmnes_util-0.0.0/src/fdmnes_util/fdm_photoenergy.py +64 -0
  49. fdmnes_util-0.0.0/src/fdmnes_util/fdm_result_files.py +105 -0
  50. fdmnes_util-0.0.0/src/fdmnes_util/fdm_sd.py +187 -0
  51. fdmnes_util-0.0.0/src/fdmnes_util/fdm_sd_2016.py +343 -0
  52. fdmnes_util-0.0.0/src/fdmnes_util/fdm_sd_2020.py +338 -0
  53. fdmnes_util-0.0.0/src/fdmnes_util/fdm_structure.py +249 -0
  54. fdmnes_util-0.0.0/src/fdmnes_util/fdm_txt.py +198 -0
  55. fdmnes_util-0.0.0/src/fdmnes_util/fdm_xyz.py +83 -0
  56. fdmnes_util-0.0.0/src/fdmnes_util/fdmfile.py +127 -0
  57. fdmnes_util-0.0.0/src/fdmnes_util/pdb.py +89 -0
  58. fdmnes_util-0.0.0/src/fdmnes_util/plot/__init__.py +2 -0
  59. fdmnes_util-0.0.0/src/fdmnes_util/plot/_figure.py +33 -0
  60. fdmnes_util-0.0.0/src/fdmnes_util/plot/plot_fdm_average.py +154 -0
  61. fdmnes_util-0.0.0/src/fdmnes_util/plot/plot_fdm_dos.py +593 -0
  62. fdmnes_util-0.0.0/src/fdmnes_util/plot/plot_fdm_xas.py +294 -0
  63. fdmnes_util-0.0.0/src/fdmnes_util/plot/plot_fdm_xas_ldos.py +163 -0
  64. fdmnes_util-0.0.0/src/fdmnes_util/structure_conversion.py +60 -0
  65. fdmnes_util-0.0.0/src/fdmnes_util/vasp_poscar.py +52 -0
  66. fdmnes_util-0.0.0/src/fdmnes_util/xyz.py +77 -0
  67. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/PKG-INFO +157 -0
  68. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/SOURCES.txt +100 -0
  69. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/dependency_links.txt +1 -0
  70. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/entry_points.txt +2 -0
  71. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/requires.txt +12 -0
  72. fdmnes_util-0.0.0/src/fdmnes_util.egg-info/top_level.txt +1 -0
  73. fdmnes_util-0.0.0/tests/test_athena_nor.py +51 -0
  74. fdmnes_util-0.0.0/tests/test_average_axis_limits.py +36 -0
  75. fdmnes_util-0.0.0/tests/test_average_broad_overlay.py +55 -0
  76. fdmnes_util-0.0.0/tests/test_average_energy_offset_v39.py +48 -0
  77. fdmnes_util-0.0.0/tests/test_average_energy_reference_v40.py +51 -0
  78. fdmnes_util-0.0.0/tests/test_average_orbital_groups.py +51 -0
  79. fdmnes_util-0.0.0/tests/test_cif.py +40 -0
  80. fdmnes_util-0.0.0/tests/test_commands.py +255 -0
  81. fdmnes_util-0.0.0/tests/test_convolution_writer_v16.py +39 -0
  82. fdmnes_util-0.0.0/tests/test_experiment_comparison.py +30 -0
  83. fdmnes_util-0.0.0/tests/test_fd_multi_3.py +46 -0
  84. fdmnes_util-0.0.0/tests/test_fd_pdos_xas_average_cli.py +144 -0
  85. fdmnes_util-0.0.0/tests/test_fd_xas_specified.py +38 -0
  86. fdmnes_util-0.0.0/tests/test_fdm_average.py +106 -0
  87. fdmnes_util-0.0.0/tests/test_fdm_to_vasp.py +91 -0
  88. fdmnes_util-0.0.0/tests/test_fdm_xyz_format.py +41 -0
  89. fdmnes_util-0.0.0/tests/test_historical_bug_scripts.py +36 -0
  90. fdmnes_util-0.0.0/tests/test_ldos0_specified.py +57 -0
  91. fdmnes_util-0.0.0/tests/test_ldos_multi.py +90 -0
  92. fdmnes_util-0.0.0/tests/test_occupied_ldos.py +42 -0
  93. fdmnes_util-0.0.0/tests/test_photoenergy_v24.py +52 -0
  94. fdmnes_util-0.0.0/tests/test_plot_multi2.py +48 -0
  95. fdmnes_util-0.0.0/tests/test_plot_package.py +47 -0
  96. fdmnes_util-0.0.0/tests/test_readers.py +323 -0
  97. fdmnes_util-0.0.0/tests/test_script_installer.py +52 -0
  98. fdmnes_util-0.0.0/tests/test_sd_dispatch.py +38 -0
  99. fdmnes_util-0.0.0/tests/test_site_spectra.py +72 -0
  100. fdmnes_util-0.0.0/tests/test_vasp_module_bridge.py +71 -0
  101. fdmnes_util-0.0.0/tests/test_write_fdm_inp.py +54 -0
  102. fdmnes_util-0.0.0/tests/test_xyz_conversion.py +28 -0
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.4
2
+ Name: fdmnes-util
3
+ Version: 0.0.0
4
+ Summary: FDMNES per-output-file Python analysis and visualization
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: numpy>=1.23
8
+ Provides-Extra: plot
9
+ Requires-Dist: matplotlib>=3.6; extra == "plot"
10
+ Provides-Extra: structure
11
+ Requires-Dist: vasp-util; extra == "structure"
12
+ Requires-Dist: ase>=3.22; extra == "structure"
13
+ Provides-Extra: test
14
+ Requires-Dist: pytest; extra == "test"
15
+ Requires-Dist: matplotlib; extra == "test"
16
+
17
+ # fdmnes_util
18
+
19
+ [![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/ohara-lab-su/fdmnes_util/blob/main/README.md)
20
+ [![ja](https://img.shields.io/badge/lang-ja-yellow.svg)](https://github.com/ohara-lab-su/fdmnes_util/blob/main/README.ja.md)
21
+
22
+ [![GitHub](https://img.shields.io/badge/GitHub-ohara--lab--su%2Ffdmnes_util-181717?logo=github)](https://github.com/ohara-lab-su/fdmnes_util/)
23
+ [![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Documentation-222222?logo=githubpages&logoColor=white)](https://ohara-lab-su.github.io/fdmnes_util/)
24
+ [![Ohara Lab](https://img.shields.io/badge/Ohara%20Lab-Home-4B5563?logo=homeassistant&logoColor=white)](https://ohara-lab-su.github.io/)
25
+
26
+ A Python class library for reading and analyzing FDMNES input and output files.
27
+
28
+ FDMNES produces different types of files for calculation settings, calculation logs, XANES spectra, site- and orbital-resolved density of states (SD), and convolved spectra. This package groups file operations by format, including reading and writing where supported. Numerical analysis and plotting belong to separate classes.
29
+
30
+ ## Development history
31
+
32
+ `fdmnes_util` is based on the FDMNES-related programs I developed around 2014 for [Structural Analysis Environment (SAE)](https://github.com/ohara-lab-su/sae). At the time, I added functions to SAE whenever I needed them for XANES calculations and analysis. The work on SAE was also described in SPring-8 publications, while the programs themselves were shared directly with colleagues and other interested users. This was before I started using Git.
33
+
34
+ At SPring-8 BL14B2, I was also involved in introducing FDMNES to XAFS users through training workshops and related activities. I later transferred from BL14B2 to JASRI's Controls and Computing Division, and development of the FDMNES tools in SAE stopped. I continued to take part in FDMNES workshops, however. Some materials are still available: the [2016 FDMNES hands-on session (PDF, Japanese)](https://support.spring8.or.jp/new/assets/materials/190228_4.nakada_160128.pdf), the [2019 workshop materials](https://support.spring8.or.jp/new/event-materials.html), and the [2019 FDMNES hands-on session (PDF, Japanese)](https://support.spring8.or.jp/assets/materials/190228_5.nakada.pdf).
35
+
36
+ Recently, I needed to use FDMNES again and dug out these programs from more than ten years ago. I thought it would be worth trying them again, so I have been getting them to work with a current Python environment. Along the way, I am reorganizing the input/output classes and moving the analysis and plotting functions from SAE's `FD*` / `fd*` scripts into the library.
37
+
38
+ There are now other libraries, including [pyFDMNES](https://github.com/tinaw/pyFDMNES). For now, though, I am not particularly interested in building a wrapper to manage the entire FDMNES calculation workflow. My priority is to restore the analysis functions I used before, then revisit the current FDMNES manual and add functions as they become useful for my research.
39
+ ## Classes
40
+
41
+ Classes are organized by file format, with reading and writing operations for a given format handled by the same class where needed. Separate classes are used when the format differs between FDMNES versions.
42
+
43
+ | File | Class | Main contents |
44
+ | --- | --- | --- |
45
+ | `*.inp` | `FdmInp` | Calculation parameters, `Filout`, and crystal information |
46
+ | `fdmfile.txt` | `Fdmfile` | List of multiple calculation input files |
47
+ | `*_bav.txt` | `FdmBav2016` / `FdmBav2020` | Calculation logs, atomic information, and energies |
48
+ | `*_sd*.txt` | `FdmSd2016` / `FdmSd2020` | LDOS, PDOS, TDOS, etc. |
49
+ | `*.txt` | `FdmTxt` | XANES spectra |
50
+ | `*_conv.txt` | `FdmConv` | Convolved spectra |
51
+
52
+ Class and module names follow Python naming conventions: for example, `FdmSd2016` is defined in `fdm_sd_2016.py`. The 2016 and 2020 formats have separate classes. The 2022 format will not be assumed to be identical to the 2020 format until actual output files have been compared.
53
+
54
+ Operations on values read from files are handled by analysis classes such as `AnalyzeFdmXas` and `AnalyzeFdmLog`. Plotting is handled by `PlotFdmXas` and `PlotFdmDos`. **Scripts call these classes rather than duplicating analysis formulas or plotting logic.**
55
+ ## Class library API
56
+
57
+ Use these references to call the public classes in `src/fdmnes_util` directly from Python.
58
+
59
+ - [Handwritten API reference](docs/en/manual_reference.md) for imports, method inputs and return values, and Python examples.
60
+ - [Sphinx-generated API](https://ohara-lab-su.github.io/fdmnes_util/en/api/) for source signatures and docstrings.
61
+ ## Example
62
+
63
+ This example retrieves the energy axis and d-orbital density of states from an SD file in the 2020 format.
64
+
65
+ ```python
66
+ from fdmnes_util.fdm_sd_2020 import FdmSd2020
67
+
68
+ sd = FdmSd2020("Fe_sd0.txt")
69
+ energy = sd.get_eng()
70
+ d_dos = sd.get_ldos("d")
71
+ ```
72
+
73
+ VASP POSCAR files are handled by importing the separate `vasp_util` package as a Python module. VASP file I/O is not duplicated in this package.
74
+ ## Installing editable example scripts
75
+
76
+ The scripts in this library are editable examples intended for users to adapt locally. After installing the Python package, run the following command in the directory where you want to perform your analysis.
77
+
78
+ ```console
79
+ fdmnes_util install script
80
+ ```
81
+
82
+ This copies the packaged example scripts to the current directory. For example, opening `FDplot_XAS.py` lets you inspect actual Python code for reading XAS files and generating plots with the class library. You can freely modify the copied scripts to suit your calculation conditions and plotting needs.
83
+
84
+ Existing scripts with the same names are not overwritten. Specify `--force` only when overwriting them, or `--directory` to change the destination.
85
+
86
+ ```console
87
+ fdmnes_util install script --directory ./analysis
88
+ fdmnes_util install script --force
89
+ ```
90
+
91
+ The editable source scripts are kept in the repository's top-level `scripts/` directory. The `pyproject.toml` configuration includes them in the wheel for installation; `setup.py` is not used. Analysis and plotting algorithms belong in the library itself, while each script provides a concrete usage example.
92
+
93
+ Editable examples corresponding to all 28 SAE scripts are included. See the command audit for the status of option and output reproduction.
94
+ ## Rebuilding the original scripts
95
+
96
+ The target is all 28 `FD*` / `fd*` scripts from SAE. Rather than preserving only their command names, the goal is to reorganize their functionality into file-reading, analysis, and plotting classes and reproduce the same operations.
97
+
98
+ Not all functions of the 28 scripts have been reproduced yet. Progress and command options that remain unverified are documented in [`COMMAND_AUDIT.md`](.PROGRESS/COMMAND_AUDIT.md).
99
+
100
+ `FDplot_XASs` reads and plots convolved spectra for multiple absorbing sites. The original `-o` option specifies display of experimental data. Athena `*_obs.txt.nor` files are read using `AthenaNor`. Conversion to a Fermi-level-referenced energy axis is also separated into an analysis class. Compatibility with all options of the original script still needs to be checked; full equivalence has not yet been established.
101
+ ## References
102
+
103
+ - [SAE (Structural Analysis Environment)](https://github.com/ohara-lab-su/sae)
104
+
105
+ ## Coding conventions
106
+
107
+ Python modules include shebangs and docstrings. Class and public-method documentation follows Google style. Readability takes precedence over one-line expressions and compressed control flow.
108
+ ## Plotting package
109
+
110
+ Plotting classes live in `fdmnes_util.plot`, separately from command-line entry points. `FDplot_XAS_LDOS` produces a stacked XAS and site-resolved LDOS figure. Select the verified SD layout explicitly with `--year 2016` or `--year 2020`.
111
+ ## Rebuilding `fdLDOS0_specified`
112
+
113
+ The command retains the original `--emin`, `--emax`, and `--dmax` options and plots p-orbital LDOS. Rather than fixing the results directory, it uses `Filout` from the input file. Reading is handled by the version-specific `FdmSd2016` or `FdmSd2020` class, and plotting by `PlotFdmDos`.
114
+
115
+ ```console
116
+ python fdLDOS0_specified.py -i read_pdb.inp --year 2020 --emin -10 --emax 20 --dmax 3
117
+ ```
118
+
119
+ The command outputs EPS, PDF, and PNG files. Unlike the original script, it does not display an interactive plot window. The 2022 format is not processed as the 2020 format because actual output data has not yet been checked.
120
+
121
+ The `fdXAS_specified.py` example has also been added. Fermi-level-referenced energy conversion from the original SAE script is handled by an analysis class, and plotting uses a class in `plot/`.
122
+ ## VASP integration
123
+
124
+ POSCAR reading is delegated to the separate `vasp_util` package. No VASP parser is implemented within `fdmnes_util`. `FDvasp2fdm.py` is an example that reads POSCAR through `VaspPoscarFile` and writes the FDMNES structure section with `FdmStructure`.
125
+
126
+ ```console
127
+ fdmnes_util install script
128
+ python FDvasp2fdm.py -i POSCAR
129
+ ```
130
+
131
+ `FDfdm2vasp.py` uses ASE to write POSCAR from an FDMNES `Crystal` or `Molecule` section. For molecules, `--vacuum` specifies the vacuum padding (10 Å on each side by default).
132
+
133
+ `FDvasp2fdm.py` creates a structure file and `read_pdb.inp` with calculation parameters from POSCAR. `FdmInp` generates the input file, while `FdmStructure` writes the crystal structure.
134
+ ## File-based classes
135
+
136
+ Modules and classes are organized by FDMNES file format, rather than by read/write operations. For example, `FdmInp` in `fdm_inp.py` and `Fdmfile` in `fdmfile.py` handle operations for their respective formats. BAV and SD retain separate 2016 and 2020 classes for their differing formats.
137
+ ## CIF conversion example
138
+
139
+ Added `FDcif2fdm.py`. The original SAE script reads CIF but only prints `bug version`; the conversion here is a new extension, not a faithful reconstruction of a working original. It uses ASE through `Cif` and `FdmStructure`.
140
+
141
+ ### Selecting an SD format
142
+
143
+ Select the verified SD layout explicitly with `FdmSd(..., format_year=2016).select_reader()` or `format_year=2020`. Unverified years are not automatically treated as the 2020 layout.
144
+
145
+ ### Averaging PDOS across calculations (v28)
146
+
147
+ The editable `fdPDOS_XAS_av.py` example averages orbital PDOS across SD files after validating matching energy grids. The original SAE options for XAS overlay and energy-reference switching remain to be ported.
148
+
149
+ Added the editable `fdMulti_3.py` example for comparing LDOS from three independent calculations aligned to their respective Fermi levels.
150
+
151
+ ### v37: Averaged XAS overlay
152
+
153
+ In `fdPDOS_XAS_av.py`, use `--xas-files` for convolved XAS and `--raw-xas-files` for unbroadened XAS to overlay both averaged spectra. Each family is averaged on its own energy grid. SAE energy-reference conversion is not yet reproduced.
154
+
155
+ ### v40: averaged PDOS/XAS energy reference
156
+
157
+ The editable `fdPDOS_XAS_av.py` example accepts `--input` and `--raw-xas-files` to determine the energy reference from the FDMNES input mode and the raw XAS edge/Fermi metadata. Use `--fermi` for a Fermi-relative axis. `--energy-offset` remains an additional correction.
@@ -0,0 +1,141 @@
1
+ # fdmnes_util
2
+
3
+ [![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/ohara-lab-su/fdmnes_util/blob/main/README.md)
4
+ [![ja](https://img.shields.io/badge/lang-ja-yellow.svg)](https://github.com/ohara-lab-su/fdmnes_util/blob/main/README.ja.md)
5
+
6
+ [![GitHub](https://img.shields.io/badge/GitHub-ohara--lab--su%2Ffdmnes_util-181717?logo=github)](https://github.com/ohara-lab-su/fdmnes_util/)
7
+ [![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Documentation-222222?logo=githubpages&logoColor=white)](https://ohara-lab-su.github.io/fdmnes_util/)
8
+ [![Ohara Lab](https://img.shields.io/badge/Ohara%20Lab-Home-4B5563?logo=homeassistant&logoColor=white)](https://ohara-lab-su.github.io/)
9
+
10
+ A Python class library for reading and analyzing FDMNES input and output files.
11
+
12
+ FDMNES produces different types of files for calculation settings, calculation logs, XANES spectra, site- and orbital-resolved density of states (SD), and convolved spectra. This package groups file operations by format, including reading and writing where supported. Numerical analysis and plotting belong to separate classes.
13
+
14
+ ## Development history
15
+
16
+ `fdmnes_util` is based on the FDMNES-related programs I developed around 2014 for [Structural Analysis Environment (SAE)](https://github.com/ohara-lab-su/sae). At the time, I added functions to SAE whenever I needed them for XANES calculations and analysis. The work on SAE was also described in SPring-8 publications, while the programs themselves were shared directly with colleagues and other interested users. This was before I started using Git.
17
+
18
+ At SPring-8 BL14B2, I was also involved in introducing FDMNES to XAFS users through training workshops and related activities. I later transferred from BL14B2 to JASRI's Controls and Computing Division, and development of the FDMNES tools in SAE stopped. I continued to take part in FDMNES workshops, however. Some materials are still available: the [2016 FDMNES hands-on session (PDF, Japanese)](https://support.spring8.or.jp/new/assets/materials/190228_4.nakada_160128.pdf), the [2019 workshop materials](https://support.spring8.or.jp/new/event-materials.html), and the [2019 FDMNES hands-on session (PDF, Japanese)](https://support.spring8.or.jp/assets/materials/190228_5.nakada.pdf).
19
+
20
+ Recently, I needed to use FDMNES again and dug out these programs from more than ten years ago. I thought it would be worth trying them again, so I have been getting them to work with a current Python environment. Along the way, I am reorganizing the input/output classes and moving the analysis and plotting functions from SAE's `FD*` / `fd*` scripts into the library.
21
+
22
+ There are now other libraries, including [pyFDMNES](https://github.com/tinaw/pyFDMNES). For now, though, I am not particularly interested in building a wrapper to manage the entire FDMNES calculation workflow. My priority is to restore the analysis functions I used before, then revisit the current FDMNES manual and add functions as they become useful for my research.
23
+ ## Classes
24
+
25
+ Classes are organized by file format, with reading and writing operations for a given format handled by the same class where needed. Separate classes are used when the format differs between FDMNES versions.
26
+
27
+ | File | Class | Main contents |
28
+ | --- | --- | --- |
29
+ | `*.inp` | `FdmInp` | Calculation parameters, `Filout`, and crystal information |
30
+ | `fdmfile.txt` | `Fdmfile` | List of multiple calculation input files |
31
+ | `*_bav.txt` | `FdmBav2016` / `FdmBav2020` | Calculation logs, atomic information, and energies |
32
+ | `*_sd*.txt` | `FdmSd2016` / `FdmSd2020` | LDOS, PDOS, TDOS, etc. |
33
+ | `*.txt` | `FdmTxt` | XANES spectra |
34
+ | `*_conv.txt` | `FdmConv` | Convolved spectra |
35
+
36
+ Class and module names follow Python naming conventions: for example, `FdmSd2016` is defined in `fdm_sd_2016.py`. The 2016 and 2020 formats have separate classes. The 2022 format will not be assumed to be identical to the 2020 format until actual output files have been compared.
37
+
38
+ Operations on values read from files are handled by analysis classes such as `AnalyzeFdmXas` and `AnalyzeFdmLog`. Plotting is handled by `PlotFdmXas` and `PlotFdmDos`. **Scripts call these classes rather than duplicating analysis formulas or plotting logic.**
39
+ ## Class library API
40
+
41
+ Use these references to call the public classes in `src/fdmnes_util` directly from Python.
42
+
43
+ - [Handwritten API reference](docs/en/manual_reference.md) for imports, method inputs and return values, and Python examples.
44
+ - [Sphinx-generated API](https://ohara-lab-su.github.io/fdmnes_util/en/api/) for source signatures and docstrings.
45
+ ## Example
46
+
47
+ This example retrieves the energy axis and d-orbital density of states from an SD file in the 2020 format.
48
+
49
+ ```python
50
+ from fdmnes_util.fdm_sd_2020 import FdmSd2020
51
+
52
+ sd = FdmSd2020("Fe_sd0.txt")
53
+ energy = sd.get_eng()
54
+ d_dos = sd.get_ldos("d")
55
+ ```
56
+
57
+ VASP POSCAR files are handled by importing the separate `vasp_util` package as a Python module. VASP file I/O is not duplicated in this package.
58
+ ## Installing editable example scripts
59
+
60
+ The scripts in this library are editable examples intended for users to adapt locally. After installing the Python package, run the following command in the directory where you want to perform your analysis.
61
+
62
+ ```console
63
+ fdmnes_util install script
64
+ ```
65
+
66
+ This copies the packaged example scripts to the current directory. For example, opening `FDplot_XAS.py` lets you inspect actual Python code for reading XAS files and generating plots with the class library. You can freely modify the copied scripts to suit your calculation conditions and plotting needs.
67
+
68
+ Existing scripts with the same names are not overwritten. Specify `--force` only when overwriting them, or `--directory` to change the destination.
69
+
70
+ ```console
71
+ fdmnes_util install script --directory ./analysis
72
+ fdmnes_util install script --force
73
+ ```
74
+
75
+ The editable source scripts are kept in the repository's top-level `scripts/` directory. The `pyproject.toml` configuration includes them in the wheel for installation; `setup.py` is not used. Analysis and plotting algorithms belong in the library itself, while each script provides a concrete usage example.
76
+
77
+ Editable examples corresponding to all 28 SAE scripts are included. See the command audit for the status of option and output reproduction.
78
+ ## Rebuilding the original scripts
79
+
80
+ The target is all 28 `FD*` / `fd*` scripts from SAE. Rather than preserving only their command names, the goal is to reorganize their functionality into file-reading, analysis, and plotting classes and reproduce the same operations.
81
+
82
+ Not all functions of the 28 scripts have been reproduced yet. Progress and command options that remain unverified are documented in [`COMMAND_AUDIT.md`](.PROGRESS/COMMAND_AUDIT.md).
83
+
84
+ `FDplot_XASs` reads and plots convolved spectra for multiple absorbing sites. The original `-o` option specifies display of experimental data. Athena `*_obs.txt.nor` files are read using `AthenaNor`. Conversion to a Fermi-level-referenced energy axis is also separated into an analysis class. Compatibility with all options of the original script still needs to be checked; full equivalence has not yet been established.
85
+ ## References
86
+
87
+ - [SAE (Structural Analysis Environment)](https://github.com/ohara-lab-su/sae)
88
+
89
+ ## Coding conventions
90
+
91
+ Python modules include shebangs and docstrings. Class and public-method documentation follows Google style. Readability takes precedence over one-line expressions and compressed control flow.
92
+ ## Plotting package
93
+
94
+ Plotting classes live in `fdmnes_util.plot`, separately from command-line entry points. `FDplot_XAS_LDOS` produces a stacked XAS and site-resolved LDOS figure. Select the verified SD layout explicitly with `--year 2016` or `--year 2020`.
95
+ ## Rebuilding `fdLDOS0_specified`
96
+
97
+ The command retains the original `--emin`, `--emax`, and `--dmax` options and plots p-orbital LDOS. Rather than fixing the results directory, it uses `Filout` from the input file. Reading is handled by the version-specific `FdmSd2016` or `FdmSd2020` class, and plotting by `PlotFdmDos`.
98
+
99
+ ```console
100
+ python fdLDOS0_specified.py -i read_pdb.inp --year 2020 --emin -10 --emax 20 --dmax 3
101
+ ```
102
+
103
+ The command outputs EPS, PDF, and PNG files. Unlike the original script, it does not display an interactive plot window. The 2022 format is not processed as the 2020 format because actual output data has not yet been checked.
104
+
105
+ The `fdXAS_specified.py` example has also been added. Fermi-level-referenced energy conversion from the original SAE script is handled by an analysis class, and plotting uses a class in `plot/`.
106
+ ## VASP integration
107
+
108
+ POSCAR reading is delegated to the separate `vasp_util` package. No VASP parser is implemented within `fdmnes_util`. `FDvasp2fdm.py` is an example that reads POSCAR through `VaspPoscarFile` and writes the FDMNES structure section with `FdmStructure`.
109
+
110
+ ```console
111
+ fdmnes_util install script
112
+ python FDvasp2fdm.py -i POSCAR
113
+ ```
114
+
115
+ `FDfdm2vasp.py` uses ASE to write POSCAR from an FDMNES `Crystal` or `Molecule` section. For molecules, `--vacuum` specifies the vacuum padding (10 Å on each side by default).
116
+
117
+ `FDvasp2fdm.py` creates a structure file and `read_pdb.inp` with calculation parameters from POSCAR. `FdmInp` generates the input file, while `FdmStructure` writes the crystal structure.
118
+ ## File-based classes
119
+
120
+ Modules and classes are organized by FDMNES file format, rather than by read/write operations. For example, `FdmInp` in `fdm_inp.py` and `Fdmfile` in `fdmfile.py` handle operations for their respective formats. BAV and SD retain separate 2016 and 2020 classes for their differing formats.
121
+ ## CIF conversion example
122
+
123
+ Added `FDcif2fdm.py`. The original SAE script reads CIF but only prints `bug version`; the conversion here is a new extension, not a faithful reconstruction of a working original. It uses ASE through `Cif` and `FdmStructure`.
124
+
125
+ ### Selecting an SD format
126
+
127
+ Select the verified SD layout explicitly with `FdmSd(..., format_year=2016).select_reader()` or `format_year=2020`. Unverified years are not automatically treated as the 2020 layout.
128
+
129
+ ### Averaging PDOS across calculations (v28)
130
+
131
+ The editable `fdPDOS_XAS_av.py` example averages orbital PDOS across SD files after validating matching energy grids. The original SAE options for XAS overlay and energy-reference switching remain to be ported.
132
+
133
+ Added the editable `fdMulti_3.py` example for comparing LDOS from three independent calculations aligned to their respective Fermi levels.
134
+
135
+ ### v37: Averaged XAS overlay
136
+
137
+ In `fdPDOS_XAS_av.py`, use `--xas-files` for convolved XAS and `--raw-xas-files` for unbroadened XAS to overlay both averaged spectra. Each family is averaged on its own energy grid. SAE energy-reference conversion is not yet reproduced.
138
+
139
+ ### v40: averaged PDOS/XAS energy reference
140
+
141
+ The editable `fdPDOS_XAS_av.py` example accepts `--input` and `--raw-xas-files` to determine the energy reference from the FDMNES input mode and the raw XAS edge/Fermi metadata. Use `--fermi` for a Fermi-relative axis. `--energy-offset` remains an additional correction.
@@ -0,0 +1,28 @@
1
+ [build-system]
2
+ requires = ["setuptools>=64"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "fdmnes-util"
7
+ version = "0.0.0"
8
+ description = "FDMNES per-output-file Python analysis and visualization"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ dependencies = ["numpy>=1.23"]
12
+
13
+ [project.optional-dependencies]
14
+ plot = ["matplotlib>=3.6"]
15
+ structure = ["vasp-util", "ase>=3.22"]
16
+ test = ["pytest", "matplotlib"]
17
+
18
+ [tool.setuptools.packages.find]
19
+ where = ["src"]
20
+
21
+ [project.scripts]
22
+ fdmnes_util = "fdmnes_util.cli:main"
23
+
24
+ [tool.setuptools.package-data]
25
+ fdmnes_util = ["atomic_symbols.list"]
26
+
27
+ [tool.setuptools.data-files]
28
+ "share/fdmnes_util/scripts" = ["scripts/*.py"]
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env python3
2
+ # SAE source: sae/commands/FDbav2xyz.py
3
+ # fmt: off
4
+ # ---- SAE original header ----
5
+ # Copyright Kengo NAKADA; SAE class library.
6
+ ################################################################################
7
+ #
8
+ # *_bav.txt to xyz format
9
+ #
10
+ #
11
+ ################################################################################
12
+ #
13
+ # 2018.08.21
14
+ # Python2/3 両対応
15
+ #
16
+ # 2015.06.24 startup
17
+ #
18
+ ################################################################################
19
+ ################################################################################
20
+ # ---- End of SAE original header ----
21
+ """Extract atomic positions from a FDMNES calculation log as XYZ data."""
22
+ # fmt: on
23
+
24
+ import argparse
25
+ from pathlib import Path
26
+
27
+ from fdmnes_util.analyze_fdm_log import AnalyzeFdmLog
28
+ from fdmnes_util.fdm_bav import FdmBav
29
+ from fdmnes_util.fdm_xyz import FdmXyz
30
+
31
+
32
+ def main(argv=None):
33
+ """Load one calculation log and generate an XYZ file or print XYZ data.
34
+
35
+ Args:
36
+ argv: Optional command-line argument sequence.
37
+ """
38
+ parser = argparse.ArgumentParser(description="Convert FDMNES log to XYZ")
39
+ parser.add_argument("name", nargs="?", help="Output prefix or *_bav.txt file")
40
+ parser.add_argument("-i", "--input", help="Output prefix or *_bav.txt file")
41
+ parser.add_argument("-s", "--std", action="store_true")
42
+ options = parser.parse_args(argv)
43
+
44
+ name = options.name or options.input
45
+ if name:
46
+ log_path = Path(name)
47
+ if log_path.suffix != ".txt":
48
+ log_path = Path(f"{name}_bav.txt")
49
+ else:
50
+ log_path = Path("Cu_bav.txt")
51
+ if not log_path.is_file():
52
+ candidates = sorted(
53
+ path for path in Path.cwd().glob("*_bav.txt") if path.is_file()
54
+ )
55
+ if len(candidates) != 1:
56
+ parser.error("Specify --input when there is no unique BAV file")
57
+ log_path = candidates[0]
58
+
59
+ # The log reader handles year-specific output formats.
60
+ log = FdmBav(log_path).select_reader()
61
+ analyzer = AnalyzeFdmLog(log)
62
+ symbols, coordinates = analyzer.positions()
63
+
64
+ writer = FdmXyz()
65
+ if options.std:
66
+ print(writer.render(symbols, coordinates), end="")
67
+ else:
68
+ output_name = f"{str(log_path).removesuffix('_bav.txt')}.xyz"
69
+ output_path = writer.write(symbols, coordinates, output_name)
70
+ print(output_path)
71
+
72
+
73
+ if __name__ == "__main__":
74
+ main()
@@ -0,0 +1,64 @@
1
+ #!/usr/bin/env python3
2
+ # SAE source: sae/commands/FDcif2fdm.py.
3
+ # ---- Original SAE header (verbatim, comment text) ----
4
+ # VASP to FDMNES crystal 情報
5
+ #
6
+ # using ASE version
7
+ #
8
+ # (注意)
9
+ # 1) ASE のルーチン(cellconst) を使っている
10
+ # 2) ASE のmodule を呼び出している
11
+ #
12
+ # 2018.08.17
13
+ # Python2/3 両対応
14
+ #
15
+ # 2015.05.18 startup
16
+ # ---- End of original SAE header ----
17
+ # Original author: Kengo NAKADA; Copyright 2015, MIT.
18
+ """Convert CIF atomic structures to editable FDMNES structure sections.
19
+
20
+ The original SAE script stopped at ``bug version`` after loading the CIF.
21
+ This example completes the conversion using the public library classes.
22
+ """
23
+
24
+ import argparse
25
+ from pathlib import Path
26
+
27
+ from fdmnes_util.cif import Cif
28
+ from fdmnes_util.fdm_structure import FdmStructure
29
+
30
+
31
+ def main() -> None:
32
+ """Read a CIF file and save a FDMNES structural section."""
33
+ parser = argparse.ArgumentParser(description=__doc__)
34
+ parser.add_argument("input", nargs="?", type=Path)
35
+ parser.add_argument("-i", "--ipput", dest="input_option", type=Path)
36
+ parser.add_argument("-m", "--mol", action="store_true")
37
+ parser.add_argument("--output", type=Path)
38
+ args = parser.parse_args()
39
+
40
+ input_path = Path("POSCAR.cif")
41
+ if args.input is not None:
42
+ input_path = args.input
43
+ if args.input_option is not None:
44
+ input_path = args.input_option
45
+
46
+ structure = Cif(input_path)
47
+ if args.mol:
48
+ content = FdmStructure.render_xyz_molecule(
49
+ structure.get_symbols(),
50
+ structure.get_cartesian_positions(),
51
+ )
52
+ else:
53
+ content = FdmStructure(structure).render()
54
+
55
+ output_path = args.output
56
+ if output_path is None:
57
+ output_path = input_path.with_suffix(".fdmnes")
58
+
59
+ output_path.write_text(content, encoding="utf-8")
60
+ print(f"Wrote {output_path}")
61
+
62
+
63
+ if __name__ == "__main__":
64
+ main()
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env python3
2
+ # SAE source: sae/commands/FDclean.py
3
+ # ---- SAE original header ----
4
+ # Copyright Kengo NAKADA; SAE class library.
5
+ ################################################################################
6
+ # K.NAKADA, kengo.nakada@gmail.com
7
+ #
8
+ # FDclean
9
+ # *.in ファイルを読み込んで Filout タグから名前を取得し
10
+ # Filout* ファイルを消す
11
+ #
12
+ ################################################################################
13
+ #
14
+ # 2020.08.11: filout 処理でのセーフティーを導入
15
+ #
16
+ # 2018.08.17
17
+ # Python2/3 両対応
18
+ #
19
+ # 2015.06.19 startup
20
+ #
21
+ ################################################################################
22
+ ################################################################################
23
+ # ---- End of SAE original header ----
24
+ """Remove the generated FDMNES files belonging to the selected calculation.
25
+
26
+ The input file is preserved. This script illustrates how to combine the
27
+ input-file reader and the result-file manager. Modify the parameters to suit
28
+ your calculation directory before using it in a research workflow.
29
+ """
30
+
31
+ import argparse
32
+
33
+ from fdmnes_util.fdm_result_files import FdmResultFiles
34
+ from fdmnes_util.fdm_inp import FdmInp
35
+ from fdmnes_util.fdmfile import Fdmfile
36
+
37
+
38
+ def main(argv=None):
39
+ """Remove the output files corresponding to ``Filout``.
40
+
41
+ Args:
42
+ argv: Optional command-line argument sequence.
43
+ """
44
+ parser = argparse.ArgumentParser(description="Remove FDMNES result files")
45
+ parser.add_argument("-i", "--input")
46
+ parser.add_argument("input_path", nargs="?")
47
+ options = parser.parse_args(argv)
48
+
49
+ input_file = FdmInp(Fdmfile.select_input(options.input_path or options.input))
50
+ filout = input_file.get_filout()
51
+ if not filout:
52
+ raise ValueError("The FDMNES input file has no Filout value")
53
+
54
+ results = FdmResultFiles(filout)
55
+ deleted_files = results.clean()
56
+ for path in deleted_files:
57
+ print(f"DELETE: {path}")
58
+
59
+
60
+ if __name__ == "__main__":
61
+ main()
@@ -0,0 +1,73 @@
1
+ #!/usr/bin/env python3
2
+ # SAE original: sae/commands/FDconv_e2photoe.py
3
+ # Copyright Kengo NAKADA; SAE class library.
4
+ # K.NAKADA, kengo.nakada@gmail.com
5
+ #
6
+ # FEconv_e2photow.py
7
+ # *_conv.txt ---> *_conv_photoe.txt
8
+ # EF からの相対単位を Photon Energy 単位に変換して出力するプログラム
9
+ #
10
+ # 2018.08.17
11
+ # Python2/3 両対応
12
+ """Convert convolution energy values to photon-energy values."""
13
+
14
+ import argparse
15
+
16
+ from fdmnes_util.analyze_fdm_xas import AnalyzeFdmXas
17
+ from fdmnes_util.fdm_conv import FdmConv
18
+ from fdmnes_util.fdm_inp import FdmInp
19
+ from fdmnes_util.fdm_txt import FdmTxt
20
+ from fdmnes_util.fdm_photoenergy import FdmPhotoenergy
21
+
22
+
23
+ def main(argv=None):
24
+ """Convert the convolved spectrum and write the resulting text file.
25
+
26
+ Args:
27
+ argv: Optional command-line argument sequence.
28
+ """
29
+ parser = argparse.ArgumentParser(description="Convert XAS energy units")
30
+ parser.add_argument("input", nargs="?", help="FDMNES input file")
31
+ parser.add_argument("-i", "--inp", default="read_pdb.inp")
32
+ parser.add_argument("-t", "--text")
33
+ parser.add_argument("-c", "--conv")
34
+ parser.add_argument("-f", "--fermi", action="store_true")
35
+ options = parser.parse_args(argv)
36
+
37
+ input_name = options.inp
38
+ if options.input is not None:
39
+ input_name = options.input
40
+
41
+ input_file = FdmInp(input_name)
42
+ if input_file.get_energygpho():
43
+ raise ValueError("Input already uses PhotonEnergy")
44
+
45
+ if options.text:
46
+ raw_prefix = options.text.removesuffix(".txt")
47
+ else:
48
+ raw_prefix = input_file.get_filout()
49
+
50
+ if options.conv:
51
+ convolution_prefix = options.conv.removesuffix("_conv.txt")
52
+ else:
53
+ convolution_prefix = raw_prefix
54
+
55
+ spectrum = FdmTxt(f"{raw_prefix}.txt")
56
+ convolution = FdmConv(f"{convolution_prefix}_conv.txt")
57
+
58
+ # Energy conversion stays in the analysis class, not in this example.
59
+ energy, intensity = AnalyzeFdmXas.photon_energy(
60
+ convolution,
61
+ spectrum,
62
+ subtract_fermi=options.fermi,
63
+ fermi_energy=spectrum.get_efermi(),
64
+ )
65
+ writer = FdmPhotoenergy()
66
+ output_name = f"{convolution_prefix}_conv_photoe.txt"
67
+ output = writer.write(energy, intensity, output_name)
68
+ print(output)
69
+ return output
70
+
71
+
72
+ if __name__ == "__main__":
73
+ main()