bzx 0.1.0__tar.gz

bzx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shinya Maeyama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bzx-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.2
+Name: bzx
+Version: 0.1.0
+Summary: A Python package for BOOZ_XFORM output to GKV input
+Author-email: Shinya Maeyama <maeyama.shinya@nifs.ac.jp>
+License: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.15
+Requires-Dist: xarray>=2022.3
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.5; extra == "examples"
+Requires-Dist: booz_xform>=0.0.8; extra == "examples"
+
+# BZX - Boozer to GKV Coordinate Transformations
+---
+
+**BZX** is a Python package that transforms **BOOZ_XFORM** Boozer coordinate metrics into **GKV** field-aligned coordinates, enabling gyrokinetic analysis of **VMEC** equilibria.
+
+
+## Installation
+
+To install from PyPI:
+```bash
+pip install bzx
+```
+Or install the latest development version from GitHub:
+```bash
+pip install git+https://github.com/GKV-developers/bzx.git
+```
+If your environment has any problems with installation, you can copy the single source script file `bzx.py` from the `src/bzx/` directory and use it. 
+
+## Usage
+
+#### **(i) Basic usage: Convert to GKV input file using BZX**
+Prepare **VMEC** equilibrium output (e.g. `wout.nc`) and its **BOOZ_XFORM** output (e.g. `boozmn.nc`).
+
+```python
+from bzx import bzx
+
+# Define transformation parameters
+Ntheta_gkv = 1   # N_theta value in GKV
+nrho = 11        # Radial grid points
+ntht = 64        # Poloidal grid points
+nzeta = 0        # Toroidal grid points (nzeta=0 corresponds to output GKV field-aligned coordinates)
+alpha_fix = 0.0  # Field-line label: alpha = zeta - q*theta (not used for nzeta > 0)
+
+# Run BZX transformation
+bzx(Ntheta_gkv, nrho, ntht, nzeta, alpha_fix, 
+    fname_boozmn="boozmn.nc", fname_wout="wout.nc", 
+    output_file="./metric_boozer.bin.dat")
+```
+- Reads **VMEC output file (`wout.nc`)** and **BOOZ_XFORM output file (`boozmn.nc`)**. NetCDF format is recommended, but Binary format is also acceptable.
+- Converts them into field-aligned data and saves the result as **GKV input binary file (`metric_boozer.bin.dat`)**.
+
+
+#### **(ii) Example of workflow: From VMEC to GKV via BOOZ_XFORM and BZX**
+The script [`examples/run_vmecpp_boozxform_bzx.ipynb`](examples/run_vmecpp_boozxform_bzx.ipynb) demonstrats how to use **BZX**, starting from generating an equilibrium.
+
+- Step 1: Compute a MHD equilibrium using **VMEC++**
+    - About **VMEC++** : 
+        - [Proxima Fusion - VMEC++](https://www.proximafusion.com/press-news/introducing-vmecpp-open-source-software-for-fusion-research)
+        - [GitHub - vmecpp](https://github.com/proximafusion/vmecpp)
+
+- Step 2: Convert the **VMEC** output to Boozer coordinates using **BOOZ_XFORM**
+    - About **BOOZ_XFORM** :
+        - [BOOZ_XFORM Documentation](https://hiddensymmetries.github.io/booz_xform/)
+        - [GitHub - BOOZ_XFORM](https://github.com/hiddenSymmetries/booz_xform)
+        - [BOOZ_XFORM - STELLOPT](https://princetonuniversity.github.io/STELLOPT/BOOZ_XFORM)
+- Step 3: Convert the **BOOZ_XFORM** output to GKV coordinates using **BZX**
+    - This project.
+
+
+#### **(iii) As a command line tool**
+After installation, you can use **BZX** directly as a CLI tool in a terminal, e.g.,
+```sh
+python -m bzx --Ntheta_gkv 1 --nrho 11 --ntht 64 \
+              --nzeta 0 --alpha_fix 0.0 \
+              --fname_boozmn "boozmn.nc" --fname_wout "wout.nc" \
+              --output_file "./metric_boozer.bin.dat"
+```
+All arguments of `bzx` function is specified by keyword arguments. See also help.
+```sh
+python -m bzx --help
+```
+
+## Dependencies
+
+BZX requires the following Python packages:
+- `numpy`, `scipy`, `xarray`
+- (Optional) `matplotlib` for visualization in `examples/`
+- (Optional) `booz_xform` for `examples/run_vmecpp_boozxform_bzx.py`
+- (Optional) `vmecpp` for `examples/run_vmecpp_boozxform_bzx.py`
+
+## License
+
+This project is licensed under the MIT License. See the [`LICENSE`](LICENSE) file for details.
+
+## Author
+
+Developed by Shinya Maeyama (maeyama.shinya@nifs.ac.jp)

bzx-0.1.0/README.md

@@ -0,0 +1,87 @@
+# BZX - Boozer to GKV Coordinate Transformations
+---
+
+**BZX** is a Python package that transforms **BOOZ_XFORM** Boozer coordinate metrics into **GKV** field-aligned coordinates, enabling gyrokinetic analysis of **VMEC** equilibria.
+
+
+## Installation
+
+To install from PyPI:
+```bash
+pip install bzx
+```
+Or install the latest development version from GitHub:
+```bash
+pip install git+https://github.com/GKV-developers/bzx.git
+```
+If your environment has any problems with installation, you can copy the single source script file `bzx.py` from the `src/bzx/` directory and use it. 
+
+## Usage
+
+#### **(i) Basic usage: Convert to GKV input file using BZX**
+Prepare **VMEC** equilibrium output (e.g. `wout.nc`) and its **BOOZ_XFORM** output (e.g. `boozmn.nc`).
+
+```python
+from bzx import bzx
+
+# Define transformation parameters
+Ntheta_gkv = 1   # N_theta value in GKV
+nrho = 11        # Radial grid points
+ntht = 64        # Poloidal grid points
+nzeta = 0        # Toroidal grid points (nzeta=0 corresponds to output GKV field-aligned coordinates)
+alpha_fix = 0.0  # Field-line label: alpha = zeta - q*theta (not used for nzeta > 0)
+
+# Run BZX transformation
+bzx(Ntheta_gkv, nrho, ntht, nzeta, alpha_fix, 
+    fname_boozmn="boozmn.nc", fname_wout="wout.nc", 
+    output_file="./metric_boozer.bin.dat")
+```
+- Reads **VMEC output file (`wout.nc`)** and **BOOZ_XFORM output file (`boozmn.nc`)**. NetCDF format is recommended, but Binary format is also acceptable.
+- Converts them into field-aligned data and saves the result as **GKV input binary file (`metric_boozer.bin.dat`)**.
+
+
+#### **(ii) Example of workflow: From VMEC to GKV via BOOZ_XFORM and BZX**
+The script [`examples/run_vmecpp_boozxform_bzx.ipynb`](examples/run_vmecpp_boozxform_bzx.ipynb) demonstrats how to use **BZX**, starting from generating an equilibrium.
+
+- Step 1: Compute a MHD equilibrium using **VMEC++**
+    - About **VMEC++** : 
+        - [Proxima Fusion - VMEC++](https://www.proximafusion.com/press-news/introducing-vmecpp-open-source-software-for-fusion-research)
+        - [GitHub - vmecpp](https://github.com/proximafusion/vmecpp)
+
+- Step 2: Convert the **VMEC** output to Boozer coordinates using **BOOZ_XFORM**
+    - About **BOOZ_XFORM** :
+        - [BOOZ_XFORM Documentation](https://hiddensymmetries.github.io/booz_xform/)
+        - [GitHub - BOOZ_XFORM](https://github.com/hiddenSymmetries/booz_xform)
+        - [BOOZ_XFORM - STELLOPT](https://princetonuniversity.github.io/STELLOPT/BOOZ_XFORM)
+- Step 3: Convert the **BOOZ_XFORM** output to GKV coordinates using **BZX**
+    - This project.
+
+
+#### **(iii) As a command line tool**
+After installation, you can use **BZX** directly as a CLI tool in a terminal, e.g.,
+```sh
+python -m bzx --Ntheta_gkv 1 --nrho 11 --ntht 64 \
+              --nzeta 0 --alpha_fix 0.0 \
+              --fname_boozmn "boozmn.nc" --fname_wout "wout.nc" \
+              --output_file "./metric_boozer.bin.dat"
+```
+All arguments of `bzx` function is specified by keyword arguments. See also help.
+```sh
+python -m bzx --help
+```
+
+## Dependencies
+
+BZX requires the following Python packages:
+- `numpy`, `scipy`, `xarray`
+- (Optional) `matplotlib` for visualization in `examples/`
+- (Optional) `booz_xform` for `examples/run_vmecpp_boozxform_bzx.py`
+- (Optional) `vmecpp` for `examples/run_vmecpp_boozxform_bzx.py`
+
+## License
+
+This project is licensed under the MIT License. See the [`LICENSE`](LICENSE) file for details.
+
+## Author
+
+Developed by Shinya Maeyama (maeyama.shinya@nifs.ac.jp)

bzx-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bzx"
+version = "0.1.0"
+description = "A Python package for BOOZ_XFORM output to GKV input"
+authors = [
+    { name = "Shinya Maeyama", email = "maeyama.shinya@nifs.ac.jp" }
+]
+readme = "README.md"
+license = {text = "MIT License"}
+requires-python = ">=3.7"
+
+dependencies = [
+    "numpy>=1.23",
+    "scipy>=1.15",
+    "xarray>=2022.3",
+]
+
+[project.optional-dependencies]
+examples = [
+    "matplotlib>=3.5",
+    "booz_xform>=0.0.8",
+    #vmecpp @ git+https://github.com/proximafusion/vmecpp.git",
+]
+
+[tool.setuptools]
+packages = ["bzx"]
+package-dir = {"" = "src"}
+

bzx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bzx-0.1.0/src/bzx/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+from .bzx import bzx, Boozmn, Metric, read_GKV_metric_file

bzx-0.1.0/src/bzx/__main__.py

@@ -0,0 +1,2 @@
+from .bzx import main
+main()