yancc 0.0.1__tar.gz

yancc-0.0.1/CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use yancc in published work, please cite it as below."
+title: "yancc: Yet Another NeoClassical Code"
+abstract: >-
+  yancc is a pure-Python, JAX-based code for solving the drift kinetic equation
+  to compute neoclassical flows and transport fluxes in toroidal magnetic
+  confinement geometries, including both tokamaks and stellarators. It solves
+  the full (multi-species, energy-dependent) drift kinetic equation as well as
+  the monoenergetic approximation, using a matrix-free Krylov solver with a
+  geometric multigrid preconditioner. Being written in JAX, it is
+  differentiable and runs on both CPUs and GPUs.
+type: software
+authors:
+  - given-names: Rory
+    family-names: Conlin
+    email: mail@fouriest.net
+    affiliation: >-
+      Institute for Research in Electronics and Applied Physics,
+      University of Maryland, College Park
+    orcid: 'https://orcid.org/0000-0001-8366-2111'
+  - given-names: Matt
+    family-names: Landreman
+    affiliation: >-
+      Institute for Research in Electronics and Applied Physics,
+      University of Maryland, College Park
+    orcid: 'https://orcid.org/0000-0002-7233-577X'
+keywords:
+  - neoclassical transport
+  - drift kinetic equation
+  - stellarator
+  - tokamak
+  - plasma physics
+  - magnetic confinement fusion
+  - automatic differentiation
+  - JAX
+  - GPU
+url: "https://yancc.readthedocs.io/"
+repository-code: "https://github.com/f0uriest/yancc"
+repository-artifact: "https://pypi.org/project/yancc/"
+license: MIT

yancc-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rory Conlin
+
+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.

yancc-0.0.1/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.rst
+include CITATION.cff
+include versioneer.py
+include yancc/_version.py
+exclude .pymon
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .pymon
+prune docs
+prune local
+prune benchmarks
+prune publications
+prune htmlcov

yancc-0.0.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: yancc
+Version: 0.0.1
+Summary: Yet Another NeoClassical Code
+Author-email: Rory Conlin <mail@fouriest.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/f0uriest/yancc
+Project-URL: Documentation, https://yancc.readthedocs.io/
+Project-URL: Source Code, https://github.com/f0uriest/yancc/
+Project-URL: Issues Tracker, https://github.com/f0uriest/yancc/issues
+Keywords: neoclassical,transport,stellarator,tokamak,plasma
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: equinox<0.14,>=0.11.0
+Requires-Dist: interpax<0.4,>=0.3.3
+Requires-Dist: jax<0.11,>=0.4.30
+Requires-Dist: jaxtyping<0.4,>=0.2.24
+Requires-Dist: lineax<0.2,>=0.0.6
+Requires-Dist: netcdf4<1.8,>=1.5.4
+Requires-Dist: numpy<2.5,>=1.20.0
+Requires-Dist: orthax<0.3
+Requires-Dist: quadax<0.3,>=0.2.2
+Requires-Dist: scipy<1.18,>=1.7.0
+Provides-Extra: dev
+Requires-Dist: sympy; extra == "dev"
+Requires-Dist: desc-opt<=0.17.1; extra == "dev"
+Requires-Dist: mpmath; extra == "dev"
+Requires-Dist: sphinx<=9.1,>=3.0.0; extra == "dev"
+Requires-Dist: sphinx_copybutton<=0.5.2; extra == "dev"
+Requires-Dist: sphinx-rtd-theme<=3.1,>=1.0; extra == "dev"
+Requires-Dist: sphinx-github-style<=1.2.2,>=1.0; extra == "dev"
+Requires-Dist: ruff==0.15.14; extra == "dev"
+Requires-Dist: pre-commit<=4.5.1; extra == "dev"
+Requires-Dist: pyright<1.2; extra == "dev"
+Requires-Dist: pytest<=9.0.3,>=5.0.0; extra == "dev"
+Requires-Dist: pytest-cov<=7.1.0,>=2.6; extra == "dev"
+Requires-Dist: pytest-split<=0.11,>=0.8.2; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+.. image:: https://raw.githubusercontent.com/f0uriest/yancc/master/docs/_static/images/logo.png
+   :width: 400
+   :align: center
+   :alt: yancc
+
+Yet Another NeoClassical Code.
+==============================
+|License|
+
+|Docs| |UnitTests| |Codecov|
+
+
+``yancc`` solves the drift kinetic equation to compute neoclassical flows and transport
+fluxes in toroidal geometry (both tokamaks and stellarators).
+
+Installation
+------------
+
+``yancc`` is a pure-Python package built on `JAX <https://github.com/google/jax>`_
+and requires Python 3.10 or newer.
+
+From PyPI::
+
+    pip install yancc
+
+From source (for development)::
+
+    git clone https://github.com/f0uriest/yancc.git
+    cd yancc
+    pip install -e ".[dev]"
+
+JAX provides separate wheels for CPU and GPU backends; see the
+`JAX install guide <https://docs.jax.dev/en/latest/installation.html>`_ to pick
+the appropriate one for your hardware.
+
+Example: Solving the Drift Kinetic Equation
+-------------------------------------------
+
+A minimal end-to-end DKE solve for a single hydrogen species:
+
+.. code-block:: python
+
+    from yancc.field import Field
+    from yancc.solve import solve_dke
+    from yancc.species import Hydrogen, LocalMaxwellian
+    from yancc.velocity_grids import MaxwellSpeedGrid, UniformPitchAngleGrid
+
+    # Field and grids.
+    rho = 0.5
+    nt, nz, na, nx = 15, 31, 61, 6
+    field = Field.from_vmec("wout_NCSX.nc", rho, nt, nz)
+    pitchgrid = UniformPitchAngleGrid(na)
+    speedgrid = MaxwellSpeedGrid(nx)
+
+    # Single hydrogen species. Density and temperature gradients are with
+    # respect to rho = sqrt(normalized toroidal flux), so multiply physical
+    # gradients by the minor radius.
+    species = [
+        LocalMaxwellian(
+            Hydrogen,
+            temperature=0.8e3,                        # eV
+            density=1.5e20,                           # 1/m^3
+            dTdrho=-2.0e3 * field.a_minor,
+            dndrho=-0.4e20 * field.a_minor,
+        )
+    ]
+
+    # Radial electric field, in Volts. Erho = -dPhi/drho.
+    Er_kV_per_m = 0.5
+    Erho = Er_kV_per_m * field.a_minor * 1000
+
+    sol, info = solve_dke(
+        field,
+        pitchgrid,
+        speedgrid,
+        species,
+        Erho=Erho,
+        verbose=2,
+        rtol=1e-5,
+    )
+
+    print("<Gamma>  =", sol.get("<particle_flux>"))   # particles/(m^2 s)
+    print("<Q>      =", sol.get("<heat_flux>"))       # J/(m^2 s)
+    print("<V||B>   =", sol.get("<V||B>"))            # T*m/s
+    print("<J||B>   =", sol.get("<J||B>"))            # T*A/m^2
+
+See the `documentation <https://yancc.readthedocs.io/>`_ for the monoenergetic
+solver, multi-species runs, the full list of output variables, and the API
+reference.
+
+
+.. |License| image:: https://img.shields.io/github/license/f0uriest/yancc?color=blue&logo=open-source-initiative&logoColor=white
+    :target: https://github.com/f0uriest/yancc/blob/master/LICENSE
+    :alt: License
+
+
+.. |Docs| image:: https://img.shields.io/readthedocs/yancc?logo=Read-the-Docs
+    :target: https://yancc.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation
+
+.. |UnitTests| image:: https://github.com/f0uriest/yancc/actions/workflows/unittest.yml/badge.svg
+    :target: https://github.com/f0uriest/yancc/actions/workflows/unittest.yml
+    :alt: UnitTests
+
+.. |Codecov| image:: https://codecov.io/gh/f0uriest/yancc/branch/master/graph/badge.svg?token=4WTFZ0ZLLB
+    :target: https://codecov.io/gh/f0uriest/yancc
+    :alt: Coverage

yancc-0.0.1/README.rst

@@ -0,0 +1,107 @@
+.. image:: https://raw.githubusercontent.com/f0uriest/yancc/master/docs/_static/images/logo.png
+   :width: 400
+   :align: center
+   :alt: yancc
+
+Yet Another NeoClassical Code.
+==============================
+|License|
+
+|Docs| |UnitTests| |Codecov|
+
+
+``yancc`` solves the drift kinetic equation to compute neoclassical flows and transport
+fluxes in toroidal geometry (both tokamaks and stellarators).
+
+Installation
+------------
+
+``yancc`` is a pure-Python package built on `JAX <https://github.com/google/jax>`_
+and requires Python 3.10 or newer.
+
+From PyPI::
+
+    pip install yancc
+
+From source (for development)::
+
+    git clone https://github.com/f0uriest/yancc.git
+    cd yancc
+    pip install -e ".[dev]"
+
+JAX provides separate wheels for CPU and GPU backends; see the
+`JAX install guide <https://docs.jax.dev/en/latest/installation.html>`_ to pick
+the appropriate one for your hardware.
+
+Example: Solving the Drift Kinetic Equation
+-------------------------------------------
+
+A minimal end-to-end DKE solve for a single hydrogen species:
+
+.. code-block:: python
+
+    from yancc.field import Field
+    from yancc.solve import solve_dke
+    from yancc.species import Hydrogen, LocalMaxwellian
+    from yancc.velocity_grids import MaxwellSpeedGrid, UniformPitchAngleGrid
+
+    # Field and grids.
+    rho = 0.5
+    nt, nz, na, nx = 15, 31, 61, 6
+    field = Field.from_vmec("wout_NCSX.nc", rho, nt, nz)
+    pitchgrid = UniformPitchAngleGrid(na)
+    speedgrid = MaxwellSpeedGrid(nx)
+
+    # Single hydrogen species. Density and temperature gradients are with
+    # respect to rho = sqrt(normalized toroidal flux), so multiply physical
+    # gradients by the minor radius.
+    species = [
+        LocalMaxwellian(
+            Hydrogen,
+            temperature=0.8e3,                        # eV
+            density=1.5e20,                           # 1/m^3
+            dTdrho=-2.0e3 * field.a_minor,
+            dndrho=-0.4e20 * field.a_minor,
+        )
+    ]
+
+    # Radial electric field, in Volts. Erho = -dPhi/drho.
+    Er_kV_per_m = 0.5
+    Erho = Er_kV_per_m * field.a_minor * 1000
+
+    sol, info = solve_dke(
+        field,
+        pitchgrid,
+        speedgrid,
+        species,
+        Erho=Erho,
+        verbose=2,
+        rtol=1e-5,
+    )
+
+    print("<Gamma>  =", sol.get("<particle_flux>"))   # particles/(m^2 s)
+    print("<Q>      =", sol.get("<heat_flux>"))       # J/(m^2 s)
+    print("<V||B>   =", sol.get("<V||B>"))            # T*m/s
+    print("<J||B>   =", sol.get("<J||B>"))            # T*A/m^2
+
+See the `documentation <https://yancc.readthedocs.io/>`_ for the monoenergetic
+solver, multi-species runs, the full list of output variables, and the API
+reference.
+
+
+.. |License| image:: https://img.shields.io/github/license/f0uriest/yancc?color=blue&logo=open-source-initiative&logoColor=white
+    :target: https://github.com/f0uriest/yancc/blob/master/LICENSE
+    :alt: License
+
+
+.. |Docs| image:: https://img.shields.io/readthedocs/yancc?logo=Read-the-Docs
+    :target: https://yancc.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation
+
+.. |UnitTests| image:: https://github.com/f0uriest/yancc/actions/workflows/unittest.yml/badge.svg
+    :target: https://github.com/f0uriest/yancc/actions/workflows/unittest.yml
+    :alt: UnitTests
+
+.. |Codecov| image:: https://codecov.io/gh/f0uriest/yancc/branch/master/graph/badge.svg?token=4WTFZ0ZLLB
+    :target: https://codecov.io/gh/f0uriest/yancc
+    :alt: Coverage

yancc-0.0.1/pyproject.toml

@@ -0,0 +1,161 @@
+[build-system]
+requires = [
+  "setuptools>=77",
+  # versioneer itself is vendored as ./versioneer.py; tomli lets it read its
+  # [tool.versioneer] config from this file on Python < 3.11
+  "tomli>=1.2.0; python_version < '3.11'",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yancc"
+description = "Yet Another NeoClassical Code"
+readme = "README.rst"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [ { name = "Rory Conlin", email = "mail@fouriest.net" } ]
+keywords = [
+  "neoclassical",
+  "transport",
+  "stellarator",
+  "tokamak",
+  "plasma",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Natural Language :: English",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+  "equinox >= 0.11.0, < 0.14",
+  "interpax >= 0.3.3, < 0.4",
+  "jax >= 0.4.30, < 0.11",
+  "jaxtyping >= 0.2.24, < 0.4",
+  "lineax >= 0.0.6, < 0.2",
+  "netcdf4 >= 1.5.4, < 1.8",
+  "numpy >= 1.20.0, < 2.5",
+  "orthax < 0.3",
+  "quadax >= 0.2.2, < 0.3",
+  "scipy >= 1.7.0, < 1.18",
+]
+# version is computed from git by versioneer
+dynamic = [ "version" ]
+
+[project.optional-dependencies]
+dev = [
+  # benchmarks and analytic test oracles
+  "sympy",
+  "desc-opt <= 0.17.1",
+  "mpmath",
+  # building the docs
+  "sphinx >= 3.0.0, <= 9.1",
+  "sphinx_copybutton <= 0.5.2",
+  "sphinx-rtd-theme >= 1.0, <= 3.1",
+  "sphinx-github-style >= 1.0, <= 1.2.2",
+  # linting
+  "ruff == 0.15.14",
+  "pre-commit <= 4.5.1",
+  "pyright < 1.2",
+  # testing and benchmarking
+  "pytest >= 5.0.0, <= 9.0.3",
+  "pytest-cov >= 2.6, <= 7.1.0",
+  "pytest-split >= 0.8.2, <= 0.11",
+  # building
+  "build",
+]
+
+[project.urls]
+Homepage = "https://github.com/f0uriest/yancc"
+Documentation = "https://yancc.readthedocs.io/"
+"Source Code" = "https://github.com/f0uriest/yancc/"
+"Issues Tracker" = "https://github.com/f0uriest/yancc/issues"
+
+[tool.setuptools.packages.find]
+exclude = [ "docs*", "tests*", "local*", "benchmarks*", "publications*" ]
+
+[tool.versioneer]
+VCS = "git"
+style = "pep440"
+versionfile_source = "yancc/_version.py"
+versionfile_build = "yancc/_version.py"
+tag_prefix = "v"
+parentdir_prefix = "yancc-"
+
+[tool.pyright]
+include = [ "yancc/*.py", "tests/*.py" ]
+exclude = [
+  "yancc/_version.py",
+  "versioneer.py",
+  "docs/conf.py",
+  "local/*",
+  "*/.ipynb_checkpoints/*"
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+extend-exclude = ["docs", "build", "local", "versioneer.py", "yancc/_version.py"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "D", "ERA", "UP", "C901"]
+ignore = [
+  "E731",   # lambda expressions are useful
+  "E741",   # variable names like "l" are common for mode numbers
+  "D401",   # don't want to always use "imperative mood" in docstrings
+  "D105",   # don't care about docstrings in __dunder__ methods
+  "D205",   # rst titles in modules
+  "D400",   # rst titles in modules
+  "F722",   # to play nice with jaxtyping
+  "W505",   # doc line length handled elsewhere
+]
+
+[tool.ruff.lint.per-file-ignores]
+# need to import things to top level even if they aren't used there
+"yancc/__init__.py" = ["F401"]
+"tests/*" = ["D101", "D102", "D103"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.pytest.ini_options]
+markers = [
+  "unit: marks small unit tests",
+  "regression: marks end to end regression tests",
+  "slow: marks tests as slow (deselect with 'pytest -m \"not slow\"').",
+  "fast: mark tests as fast.",
+]
+filterwarnings = [
+  "error",
+  "ignore::pytest.PytestUnraisableExceptionWarning",
+  # ignore benign Cython warnings on ndarray size
+  "ignore:numpy.ndarray size changed:RuntimeWarning",
+  # ignore benign ml_dtypes DeprecationWarning
+  "ignore::DeprecationWarning:ml_dtypes.*",
+]
+
+[tool.coverage.run]
+# we only care about the coverage of the source itself
+# otherwise it measures coverage of the tests themselves as well
+source = [ "yancc/" ]
+# _version.py is generated code, no need to count it
+omit = [ "yancc/_version.py" ]
+
+[tool.coverage.report]
+# Regexes for lines to exclude from consideration
+exclude_lines = [
+  # Have to re-enable the standard pragma
+  "pragma: no cover",
+  "if __name__ == .__main__.:",
+]
+ignore_errors = true

yancc-0.0.1/setup.cfg

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

yancc-0.0.1/setup.py

@@ -0,0 +1,22 @@
+"""Setup/build/install script for yancc.
+
+Package metadata lives in ``pyproject.toml``. This file exists only because
+versioneer needs to inject the version and its custom build commands, which
+cannot be expressed declaratively.
+"""
+
+import os
+import sys
+
+from setuptools import setup
+
+# PEP 517 backends do not put the source root on sys.path, so the vendored
+# versioneer.py next to this file would not otherwise be importable.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import versioneer  # noqa: E402
+
+setup(
+    version=versioneer.get_version(),
+    cmdclass=versioneer.get_cmdclass(),
+)