torux 0.1.0__tar.gz

torux-0.1.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

torux-0.1.0/NOTICE.md

@@ -0,0 +1,46 @@
+# Credits
+
+torux's own code, results, text and figures are public domain ([CC0 1.0](LICENSE)), all but one picture: the twelve machines ([below](#behind-the-pictures)). What it was run on is other people's work, and keeps their licences.
+
+## Bundled inputs (`examples/`)
+
+| file | from | licence |
+|---|---|---|
+| `quasr_0000954.json`, `quasr_0219457.json`, `quasr_1100073.json` | QUASR v4, the QUAsisymmetric Stellarator Repository, Andrew Giuliani, [doi:10.5281/zenodo.13717741](https://doi.org/10.5281/zenodo.13717741) | MIT |
+| `hsx.json`, `w7x.json` | the HSX and Wendelstein 7-X coil sets shipped with [simsopt](https://github.com/hiddenSymmetries/simsopt) 1.11, rewritten as Fourier-filament JSON | MIT |
+| `d3d_icoils_upper.dat` | DIII-D's upper I-coils, from the coil library of [GPEC](https://github.com/OpenFUSIONToolkit/GPEC) | MIT |
+
+`results/compare300/inputs/`: 306 coil sets of QUASR v4 (as above, MIT), each rewritten as Fourier-filament JSON with its outermost stored surface, its VMEC namelist and its row of QUASR's table.
+
+The MIT licence texts are in [`examples/LICENCES.md`](examples/LICENCES.md).
+
+## Behind the results
+
+`results/quasr.parquet`, `results/compare300.csv` and `results/refinement.csv` are measurements on coil sets of QUASR (as above).
+
+## Behind the pictures
+
+The pictures are torux's own renderings. The coils and magnets drawn in them are other people's designs and data, under these licences. Checksums and origins of the files are in [`visuals/sources.json`](visuals/sources.json) and [`visuals/one-line.json`](visuals/one-line.json).
+
+**The picture of the twelve machines is not CC0.** `visuals/any-coil-light.png` and `visuals/any-coil-dark.png` are excluded from the dedication. Three of the machines in them are drawn from files under copyleft licences (LHD: GPL-3.0, ITER and the dipole: LGPL-3.0) and three from CC BY 4.0 data (CNT, the wireframe, MUSE). Those six renderings stay under the terms of their sources, in that picture and where each machine is drawn alone in `visuals/sources/` (`heliotron`, `tokamak`, `dipole`, `interlinked`, `wireframe`, `magnets`).
+
+| in `visuals/any-coil-*.png` and `visuals/sources/` | from | licence |
+|---|---|---|
+| QUASR 0124533 | QUASR v4, the QUAsisymmetric Stellarator Repository, by Andrew Giuliani, [doi:10.5281/zenodo.13717741](https://doi.org/10.5281/zenodo.13717741) | MIT |
+| HSX | HSX coil set from simsopt 1.11 (hiddenSymmetries/simsopt), in torux's Fourier-filament form, [github.com/hiddenSymmetries/simsopt](https://github.com/hiddenSymmetries/simsopt) | MIT |
+| Wendelstein 7-X | Wendelstein 7-X coil set from simsopt 1.11 (hiddenSymmetries/simsopt), in torux's Fourier-filament form, [github.com/hiddenSymmetries/simsopt](https://github.com/hiddenSymmetries/simsopt) | MIT |
+| LHD | LHD coil model (Y. Suzuki, 2017) from the FOCUS code's examples (PrincetonUniversity/FOCUS), [github.com/PrincetonUniversity/FOCUS](https://github.com/PrincetonUniversity/FOCUS) | GPL-3.0 |
+| CNT | CNT coil set from "Update on the design of the Columbia Stellarator eXperiment" by A. Baillod, R. Lopez, A. Veksler, M. Campagna, D. Schmeling, E. Paul and A. Knyazev, [doi:10.5281/zenodo.18115389](https://doi.org/10.5281/zenodo.18115389) | CC BY 4.0 |
+| STAR_Lite-A | STAR_Lite-A coil set (Harrer, Giuliani, Padidar, Davies, Naik and Lowe, 2026) shipped in simsopt's configs, [github.com/hiddenSymmetries/simsopt](https://github.com/hiddenSymmetries/simsopt) | MIT |
+| wireframe (RCLS) | wireframe from "Data and code for A framework for discrete optimization of stellarator coils" by Kenneth Hammond, [doi:10.34770/6pbm-9981](https://doi.org/10.34770/6pbm-9981) | CC BY 4.0 |
+| MUSE | MUSE zot43 magnet and coil model from the "QUADCOIL Quasi-single-stage Dataset" by Lanke Fu, [doi:10.5281/zenodo.19923438](https://doi.org/10.5281/zenodo.19923438) | CC BY 4.0 |
+| US131 (umbilic) | US131 coil set from "Omnigenous umbilic stellarators: data and analysis files" by Rahul Gaur, [doi:10.5281/zenodo.15355215](https://doi.org/10.5281/zenodo.15355215) | MIT |
+| ITER | ITER coil geometry of the TokaMaker examples (OpenFUSIONToolkit), [github.com/OpenFUSIONToolkit/OpenFUSIONToolkit](https://github.com/OpenFUSIONToolkit/OpenFUSIONToolkit) | LGPL-3.0 |
+| DIII-D upper I-coils | DIII-D upper I-coil geometry of the GPEC coil library (OpenFUSIONToolkit/GPEC), [github.com/OpenFUSIONToolkit/GPEC](https://github.com/OpenFUSIONToolkit/GPEC) | MIT |
+| LDX-like dipole | LDX-like dipole of the TokaMaker examples (OpenFUSIONToolkit), [github.com/OpenFUSIONToolkit/OpenFUSIONToolkit](https://github.com/OpenFUSIONToolkit/OpenFUSIONToolkit) | LGPL-3.0 |
+
+`visuals/one-line-*`: the coils of Wendelstein 7-X, from the coil set shipped with [simsopt](https://github.com/hiddenSymmetries/simsopt) 1.11 (MIT).
+
+`visuals/plot-*`: the coils of QUASR design 954, from QUASR v4 (as above, MIT), as `torux.solve("examples/quasr_0000954.json").plot` draws them.
+
+GPL-3.0: [gnu.org/licenses/gpl-3.0](https://www.gnu.org/licenses/gpl-3.0.html). LGPL-3.0: [gnu.org/licenses/lgpl-3.0](https://www.gnu.org/licenses/lgpl-3.0.html). CC BY 4.0: [creativecommons.org/licenses/by/4.0](https://creativecommons.org/licenses/by/4.0/). Every picture is a new rendering of the geometry in the files named. Of those files, only the ones listed under bundled inputs are redistributed here.

torux-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: torux
+Version: 0.1.0
+Summary: Vacuum magnetic field and flux surfaces of coils and magnets for toroidal confinement, at the limit of double-precision arithmetic.
+Author: Philipp Bogdan
+License: CC0-1.0
+Project-URL: Repository, https://github.com/philippbogdan/torux
+Keywords: stellarator,plasma physics,magnetic confinement,flux surfaces,fusion
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: numpy>=2.4
+Requires-Dist: scipy>=1.18
+Requires-Dist: jax>=0.9
+Requires-Dist: numba>=0.65
+Requires-Dist: mpmath>=1.3
+Requires-Dist: threadpoolctl>=3.1
+Provides-Extra: hdf5
+Requires-Dist: h5py>=3.10; extra == "hdf5"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.9; extra == "plot"
+Provides-Extra: all
+Requires-Dist: h5py>=3.10; extra == "all"
+Requires-Dist: matplotlib>=3.9; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pandas>=2; extra == "test"
+Requires-Dist: pyarrow>=15; extra == "test"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/torux-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/torux-light.png" width="830" alt="TORUX">
+  </picture>
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/any-coil-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/any-coil-light.png" width="838" alt="Twelve magnet systems for fusion stand in three rows of four, drawn in copper: stellarator coil sets of many shapes, a wireframe, a ring of permanent magnets inside upright coils, the coils of the ITER tokamak, six window-frame coils and a levitated ring. Inside nine of them, teal light woven from field lines fills the vacuum magnetic surface torux verified. The last three, ITER's coils, DIII-D's I-coils and the dipole, hold no light: thin grey field lines loop round their coils instead and never go round the machine.">
+  </picture>
+</p>
+
+<h1 align="center">Arithmetic limit, extremely fast. Any coil works.</h1>
+
+<p align="center"><sub>(The aspiration. torux is in development, and vacuum only for now: no finite pressure.)</sub></p>
+
+**Give torux the coils of a stellarator. Three seconds later you have the magnetic surface they make, right to the fifteenth digit: the last one a computer holds.**
+
+It has done that for 231,878 of the 371,701 coil sets in [QUASR](https://quasr.flatironinstitute.org), a public database of stellarator designs, in a median of three seconds each. A second evaluator, sharing no code with the solver, checked every one. For 5,206 more it returned a certificate that the surface asked for cannot exist, and for another 846 a weaker one. It never guesses: the other 133,771 it calls undetermined, three in four of them after less than a minute's work.
+
+Above: twelve kinds of magnet, one solver. Nine carry the surface torux verified for them, drawn as light. The other three (a tokamak's poloidal coils, its perturbation coils, a levitated dipole) carry none, and that is an answer too: their field lines, the thin grey ones, close round the coils and never go round the machine, so no surface can enclose toroidal flux, and torux proves it. (A tokamak's surfaces need the current in its plasma, and a dipole holds its plasma on the closed lines themselves.) [Each one, close up.](https://github.com/philippbogdan/torux/blob/main/visuals/README.md)
+
+## Fifteen digits
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/accuracy-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/accuracy-light.svg" width="838" alt="One row of dots for each tool on a logarithmic axis of the field crossing a surface, from 10 to the minus 15 up to 1. torux: 201 dots between 3 times 10 to the minus 16 and 7 times 10 to the minus 15, median 1 times 10 to the minus 15. SIMSOPT BoozerLS: 283 dots between 2 times 10 to the minus 15 and 4 times 10 to the minus 2, median 2 times 10 to the minus 8. SIMSOPT BoozerExact: 288 dots between 5 times 10 to the minus 15 and 2 times 10 to the minus 1, median 3 times 10 to the minus 8. SIMSOPT QFM: 297 dots between 5 times 10 to the minus 14 and 1, median 3 times 10 to the minus 7. VMEC++: 252 dots between 2 times 10 to the minus 6 and 2 times 10 to the minus 1, median 9 times 10 to the minus 4. DESC: 199 dots between 3 times 10 to the minus 8 and 2 times 10 to the minus 1, median 3 times 10 to the minus 3. QUASR's stored surface: 300 dots between 8 times 10 to the minus 9 and 2 times 10 to the minus 1, median 9 times 10 to the minus 4.">
+</picture>
+
+Three hundred coil sets drawn at random from QUASR. Every tool gets the same coils, the same requested flux and an hour on four threads for each. The other five need settings, and we chose them: the route each tool's documentation recommends, pushed wherever that paid on six coil sets outside the 300. torux has no settings to choose. One judge: an evaluator that shares no code with any of them, working in extended precision at 4,000 random points of each surface. A dot is a coil set. Its place is how much of the field leaks through the surface. [How each tool was run, and how to run a row again.](https://github.com/philippbogdan/torux/blob/main/results/compare300/README.md)
+
+torux's surfaces leak 1.1 × 10⁻¹⁵, within 2.9 times the least that a surface written in double precision can leak. The worst of its 201 leaks 6.8 × 10⁻¹⁵. On the 199 coil sets both solved, the closest tool, SIMSOPT BoozerExact, leaks 700,000 times more: 5 orders of magnitude. The surfaces the designs are stored with, where every solve starts, leak 8.9 × 10⁻⁴: they are coarse, a few hundred Fourier terms each, where torux's take thousands. [Every dot is a row of `results/compare300.csv`.](https://github.com/philippbogdan/torux/blob/main/results/compare300.csv)
+
+| | surfaces returned | median leak | within 10⁻¹² | median seconds |
+|---|---:|---:|---:|---:|
+| **torux** | 201 of 300 | 1.1 × 10⁻¹⁵ | 201 | 4.2 |
+| SIMSOPT BoozerLS | 283 of 300 | 2.4 × 10⁻⁸ | 38 | 824 |
+| SIMSOPT BoozerExact | 288 of 300 | 2.7 × 10⁻⁸ | 51 | 67 |
+| SIMSOPT QFM | 297 of 300 | 3.3 × 10⁻⁷ | 14 | 1,770 |
+| VMEC++ | 252 of 300 | 9.4 × 10⁻⁴ | 0 | 1,525 |
+| DESC | 199 of 300 | 2.6 × 10⁻³ | 0 | 885 |
+| QUASR's stored surface | 300 of 300 | 8.9 × 10⁻⁴ | 0 | |
+
+Nobody needs fifteen digits of a flux surface. What you need is never to wonder whether the surface is wrong or the solver. And at this precision "there is no surface" stops being a solve that failed and becomes an answer torux can certify: 22 of these 300, and 16 more by its weaker kind of certificate. The other 61 were still undetermined after their hour.
+
+## Seconds
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/time-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/time-light.svg" width="838" alt="One row of dots for each tool on a logarithmic axis of seconds, from a tenth of a second to an hour: the time at which each tool had the surface it returned. torux: median 4.2 seconds. SIMSOPT BoozerExact: median 67 seconds. SIMSOPT BoozerLS: median 824 seconds. DESC: median 885 seconds. VMEC++: median 1,525 seconds. SIMSOPT QFM: median 1,770 seconds.">
+</picture>
+
+The same 300 coil sets on one processor (AMD EPYC 7742), four threads each. A dot is a surface a tool returned, placed at the time at which the tool had it, the tool's own checks included. torux: 4.2 s in the median, and then it stops. The others were set to spend their hour on accuracy and go on working after the surface they return, VMEC++ and SIMSOPT QFM nearly always until the hour ends: that later time is not counted here.
+
+- SIMSOPT BoozerExact: 67 s. On the 199 coil sets both solved it was faster on 12 and more accurate on 0.
+- SIMSOPT BoozerLS: 824 s. On the 199 coil sets both solved it was faster on 2 and more accurate on 0.
+- DESC: 885 s. On the 141 coil sets both solved it was faster on 0 and more accurate on 0.
+- VMEC++: 1,525 s. On the 177 coil sets both solved it was faster on 1 and more accurate on 0.
+- SIMSOPT QFM: 1,770 s. On the 199 coil sets both solved it was faster on 0 and more accurate on 0.
+
+## How it works
+
+A stellarator is a fusion machine. Coils wind a magnetic field into a twisted ring, and the field holds a plasma hotter than the centre of the Sun. Follow one line of that field and it goes round and round the ring. If it never leaves one closed surface, that surface is a wall that holds the plasma in. Whether a set of coils makes such walls, and exactly where, is the first question of every design.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/one-line-dark.gif">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/one-line-light.gif" width="838" alt="Animation. The coils of the Wendelstein 7-X stellarator, cut away at the front. One magnetic field line, drawn as a point of green light, runs round inside them lap after lap, faster and faster, and its trail weaves a twisted, ring-shaped surface of fine fibres that lights the coils from inside: the magnetic surface torux computed, which the line never leaves.">
+  </picture>
+</p>
+
+<p align="center"><sub>One field line of Wendelstein 7-X, followed for 200 laps (7.3 km): it never strays more than 1.1 × 10⁻¹³ m from the surface torux computed. <a href="visuals/README.md#one-field-line">How that was measured.</a></sub></p>
+
+torux does not follow the line. It writes the surface as a sum of smooth waves and asks one thing of it: that the field crosses it nowhere. Newton's method finds the waves. Each refinement takes orders of magnitude off the error, until the digits of a 64-bit number run out:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/refinement-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/refinement-light.svg" width="838" alt="For 201 coil sets, the field crossing the surface against the number of coefficients describing it. Every line falls steeply, from between 10 to the minus 6 and 10 to the minus 12, and ends just above the limit of double precision near 10 to the minus 15.">
+</picture>
+
+Then a second program, written apart from the first and sharing none of its code, measures the leak at 4,096 random points. Only if both agree is the answer "surface".
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/answers-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/answers-light.svg" width="838" alt="Coils and a flux go to a Newton solve for the surface. If it converges, different code checks it again at 4,096 points. If that agrees, the answer is surface, and if it disagrees, undetermined. If the solve fails, torux looks for what forbids a surface, an island chain or the edge of confinement: found and bounded, the answer is no surface, with a certificate, and out of time it is undetermined.">
+</picture>
+
+When Newton fails, the surface may not be there. Near a resonance the field lines close on themselves and the surfaces break into a chain of islands. Past the edge of confinement the lines wander off and are lost. torux finds the chain or the edge, fences it with curves that no surface can cross, and bounds the flux they forbid: a certificate. That is a theorem with a measured error budget, not a machine-checked proof. Of QUASR's certificates, the 5,206 island bands rest on an exact symmetry of the field, and the 846 weaker ones are edge barriers, which rest on a weaker error model. With neither a surface nor a certificate inside its time budget, torux says so.
+
+[The method, for people who know the field.](https://github.com/philippbogdan/torux/blob/main/docs/method.md) [What is checked, and by what.](https://github.com/philippbogdan/torux/blob/main/docs/verification.md)
+
+## Use it
+
+```sh
+git clone https://github.com/philippbogdan/torux && cd torux
+pip install .
+torux solve examples/quasr_0000954.json
+```
+
+```
+surface                verified: the solver's check and an independent evaluator agree
+toroidal flux          0.069106905814 Wb
+rotational transform   -0.0975229741144
+radii                  major 0.999994679 m, minor 0.150000523 m, aspect ratio 6.66661
+volume                 0.444132929 m^3
+Fourier series         M, N = 48, 32, with 2 field periods
+field across it        1.1e-15 of |B| (the solver's own check)
+independent check      3.3e-15 of |B| across it, and the same flux to within 8e-16
+time                   0.7 s
+```
+
+The first run compiles for up to a minute. After that, seconds.
+
+```python
+import torux
+
+s = torux.solve("coils.json", minor_radius=0.15)   # or flux=0.07 (Wb), volume=0.44 (m³), largest=True
+print(s)                                 # what it found and how it was checked, or why there is no surface
+s.iota, s.volume, s.aspect_ratio         # the numbers
+s.save("input.mine")                     # a VMEC input: VMEC, VMEC++, DESC and SIMSOPT read it
+s.plot("mine.png")                       # the picture below
+s.boozer().quasisymmetry                 # |B| in Boozer angles, and how far it is from quasi-symmetry
+
+torux.check("coils.json", "wout_other.nc")    # a surface from another code: how much of the field crosses it
+torux.many(files, table="answers.csv")        # a folder of designs, one row each
+```
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/plot-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/plot-light.png" width="760" alt="What s.plot draws for the surface above: on the left the flux surface as a green torus, shaded by the strength of the field on it, threaded through its four copper coils. On the right are its cross-sections at three toroidal angles, an ellipse lying flat, a rounded triangle and an ellipse standing upright, and the scale of the field strength, about 0.9 to 1.1 tesla.">
+  </picture>
+</p>
+
+Nothing to tune: no resolution, no tolerance, no starting guess. The coils are a file (SIMSOPT and QUASR JSON, MAKEGRID, FOCUS, permanent magnets, wireframes, a tokamak's coils), a QUASR design by its number, or a SIMSOPT or DESC object you already hold. [Usage](https://github.com/philippbogdan/torux/blob/main/docs/usage.md) and [formats](https://github.com/philippbogdan/torux/blob/main/docs/formats.md).
+
+## Credit
+
+Used torux? Say so, so the next person finds it:
+
+> Flux surfaces computed with [torux](https://github.com/philippbogdan/torux).
+
+```bibtex
+@software{bogdan2026torux,
+  author = {Bogdan, Philipp},
+  title  = {torux: vacuum flux surfaces at the limit of double-precision arithmetic},
+  year   = {2026},
+  url    = {https://github.com/philippbogdan/torux}
+}
+```
+
+Public domain, [CC0 1.0](https://github.com/philippbogdan/torux/blob/main/LICENSE), all but the picture of the twelve machines: six of them are drawn from files under GPL, LGPL and CC BY licences, and those renderings stay under their sources' terms. The coil sets torux was run on are other people's work, under their own licences: [credits](https://github.com/philippbogdan/torux/blob/main/NOTICE.md).

torux-0.1.0/README.md

@@ -0,0 +1,154 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/torux-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/torux-light.png" width="830" alt="TORUX">
+  </picture>
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/any-coil-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/any-coil-light.png" width="838" alt="Twelve magnet systems for fusion stand in three rows of four, drawn in copper: stellarator coil sets of many shapes, a wireframe, a ring of permanent magnets inside upright coils, the coils of the ITER tokamak, six window-frame coils and a levitated ring. Inside nine of them, teal light woven from field lines fills the vacuum magnetic surface torux verified. The last three, ITER's coils, DIII-D's I-coils and the dipole, hold no light: thin grey field lines loop round their coils instead and never go round the machine.">
+  </picture>
+</p>
+
+<h1 align="center">Arithmetic limit, extremely fast. Any coil works.</h1>
+
+<p align="center"><sub>(The aspiration. torux is in development, and vacuum only for now: no finite pressure.)</sub></p>
+
+**Give torux the coils of a stellarator. Three seconds later you have the magnetic surface they make, right to the fifteenth digit: the last one a computer holds.**
+
+It has done that for 231,878 of the 371,701 coil sets in [QUASR](https://quasr.flatironinstitute.org), a public database of stellarator designs, in a median of three seconds each. A second evaluator, sharing no code with the solver, checked every one. For 5,206 more it returned a certificate that the surface asked for cannot exist, and for another 846 a weaker one. It never guesses: the other 133,771 it calls undetermined, three in four of them after less than a minute's work.
+
+Above: twelve kinds of magnet, one solver. Nine carry the surface torux verified for them, drawn as light. The other three (a tokamak's poloidal coils, its perturbation coils, a levitated dipole) carry none, and that is an answer too: their field lines, the thin grey ones, close round the coils and never go round the machine, so no surface can enclose toroidal flux, and torux proves it. (A tokamak's surfaces need the current in its plasma, and a dipole holds its plasma on the closed lines themselves.) [Each one, close up.](https://github.com/philippbogdan/torux/blob/main/visuals/README.md)
+
+## Fifteen digits
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/accuracy-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/accuracy-light.svg" width="838" alt="One row of dots for each tool on a logarithmic axis of the field crossing a surface, from 10 to the minus 15 up to 1. torux: 201 dots between 3 times 10 to the minus 16 and 7 times 10 to the minus 15, median 1 times 10 to the minus 15. SIMSOPT BoozerLS: 283 dots between 2 times 10 to the minus 15 and 4 times 10 to the minus 2, median 2 times 10 to the minus 8. SIMSOPT BoozerExact: 288 dots between 5 times 10 to the minus 15 and 2 times 10 to the minus 1, median 3 times 10 to the minus 8. SIMSOPT QFM: 297 dots between 5 times 10 to the minus 14 and 1, median 3 times 10 to the minus 7. VMEC++: 252 dots between 2 times 10 to the minus 6 and 2 times 10 to the minus 1, median 9 times 10 to the minus 4. DESC: 199 dots between 3 times 10 to the minus 8 and 2 times 10 to the minus 1, median 3 times 10 to the minus 3. QUASR's stored surface: 300 dots between 8 times 10 to the minus 9 and 2 times 10 to the minus 1, median 9 times 10 to the minus 4.">
+</picture>
+
+Three hundred coil sets drawn at random from QUASR. Every tool gets the same coils, the same requested flux and an hour on four threads for each. The other five need settings, and we chose them: the route each tool's documentation recommends, pushed wherever that paid on six coil sets outside the 300. torux has no settings to choose. One judge: an evaluator that shares no code with any of them, working in extended precision at 4,000 random points of each surface. A dot is a coil set. Its place is how much of the field leaks through the surface. [How each tool was run, and how to run a row again.](https://github.com/philippbogdan/torux/blob/main/results/compare300/README.md)
+
+torux's surfaces leak 1.1 × 10⁻¹⁵, within 2.9 times the least that a surface written in double precision can leak. The worst of its 201 leaks 6.8 × 10⁻¹⁵. On the 199 coil sets both solved, the closest tool, SIMSOPT BoozerExact, leaks 700,000 times more: 5 orders of magnitude. The surfaces the designs are stored with, where every solve starts, leak 8.9 × 10⁻⁴: they are coarse, a few hundred Fourier terms each, where torux's take thousands. [Every dot is a row of `results/compare300.csv`.](https://github.com/philippbogdan/torux/blob/main/results/compare300.csv)
+
+| | surfaces returned | median leak | within 10⁻¹² | median seconds |
+|---|---:|---:|---:|---:|
+| **torux** | 201 of 300 | 1.1 × 10⁻¹⁵ | 201 | 4.2 |
+| SIMSOPT BoozerLS | 283 of 300 | 2.4 × 10⁻⁸ | 38 | 824 |
+| SIMSOPT BoozerExact | 288 of 300 | 2.7 × 10⁻⁸ | 51 | 67 |
+| SIMSOPT QFM | 297 of 300 | 3.3 × 10⁻⁷ | 14 | 1,770 |
+| VMEC++ | 252 of 300 | 9.4 × 10⁻⁴ | 0 | 1,525 |
+| DESC | 199 of 300 | 2.6 × 10⁻³ | 0 | 885 |
+| QUASR's stored surface | 300 of 300 | 8.9 × 10⁻⁴ | 0 | |
+
+Nobody needs fifteen digits of a flux surface. What you need is never to wonder whether the surface is wrong or the solver. And at this precision "there is no surface" stops being a solve that failed and becomes an answer torux can certify: 22 of these 300, and 16 more by its weaker kind of certificate. The other 61 were still undetermined after their hour.
+
+## Seconds
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/time-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/time-light.svg" width="838" alt="One row of dots for each tool on a logarithmic axis of seconds, from a tenth of a second to an hour: the time at which each tool had the surface it returned. torux: median 4.2 seconds. SIMSOPT BoozerExact: median 67 seconds. SIMSOPT BoozerLS: median 824 seconds. DESC: median 885 seconds. VMEC++: median 1,525 seconds. SIMSOPT QFM: median 1,770 seconds.">
+</picture>
+
+The same 300 coil sets on one processor (AMD EPYC 7742), four threads each. A dot is a surface a tool returned, placed at the time at which the tool had it, the tool's own checks included. torux: 4.2 s in the median, and then it stops. The others were set to spend their hour on accuracy and go on working after the surface they return, VMEC++ and SIMSOPT QFM nearly always until the hour ends: that later time is not counted here.
+
+- SIMSOPT BoozerExact: 67 s. On the 199 coil sets both solved it was faster on 12 and more accurate on 0.
+- SIMSOPT BoozerLS: 824 s. On the 199 coil sets both solved it was faster on 2 and more accurate on 0.
+- DESC: 885 s. On the 141 coil sets both solved it was faster on 0 and more accurate on 0.
+- VMEC++: 1,525 s. On the 177 coil sets both solved it was faster on 1 and more accurate on 0.
+- SIMSOPT QFM: 1,770 s. On the 199 coil sets both solved it was faster on 0 and more accurate on 0.
+
+## How it works
+
+A stellarator is a fusion machine. Coils wind a magnetic field into a twisted ring, and the field holds a plasma hotter than the centre of the Sun. Follow one line of that field and it goes round and round the ring. If it never leaves one closed surface, that surface is a wall that holds the plasma in. Whether a set of coils makes such walls, and exactly where, is the first question of every design.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/one-line-dark.gif">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/one-line-light.gif" width="838" alt="Animation. The coils of the Wendelstein 7-X stellarator, cut away at the front. One magnetic field line, drawn as a point of green light, runs round inside them lap after lap, faster and faster, and its trail weaves a twisted, ring-shaped surface of fine fibres that lights the coils from inside: the magnetic surface torux computed, which the line never leaves.">
+  </picture>
+</p>
+
+<p align="center"><sub>One field line of Wendelstein 7-X, followed for 200 laps (7.3 km): it never strays more than 1.1 × 10⁻¹³ m from the surface torux computed. <a href="visuals/README.md#one-field-line">How that was measured.</a></sub></p>
+
+torux does not follow the line. It writes the surface as a sum of smooth waves and asks one thing of it: that the field crosses it nowhere. Newton's method finds the waves. Each refinement takes orders of magnitude off the error, until the digits of a 64-bit number run out:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/refinement-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/refinement-light.svg" width="838" alt="For 201 coil sets, the field crossing the surface against the number of coefficients describing it. Every line falls steeply, from between 10 to the minus 6 and 10 to the minus 12, and ends just above the limit of double precision near 10 to the minus 15.">
+</picture>
+
+Then a second program, written apart from the first and sharing none of its code, measures the leak at 4,096 random points. Only if both agree is the answer "surface".
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/answers-dark.svg">
+  <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/answers-light.svg" width="838" alt="Coils and a flux go to a Newton solve for the surface. If it converges, different code checks it again at 4,096 points. If that agrees, the answer is surface, and if it disagrees, undetermined. If the solve fails, torux looks for what forbids a surface, an island chain or the edge of confinement: found and bounded, the answer is no surface, with a certificate, and out of time it is undetermined.">
+</picture>
+
+When Newton fails, the surface may not be there. Near a resonance the field lines close on themselves and the surfaces break into a chain of islands. Past the edge of confinement the lines wander off and are lost. torux finds the chain or the edge, fences it with curves that no surface can cross, and bounds the flux they forbid: a certificate. That is a theorem with a measured error budget, not a machine-checked proof. Of QUASR's certificates, the 5,206 island bands rest on an exact symmetry of the field, and the 846 weaker ones are edge barriers, which rest on a weaker error model. With neither a surface nor a certificate inside its time budget, torux says so.
+
+[The method, for people who know the field.](https://github.com/philippbogdan/torux/blob/main/docs/method.md) [What is checked, and by what.](https://github.com/philippbogdan/torux/blob/main/docs/verification.md)
+
+## Use it
+
+```sh
+git clone https://github.com/philippbogdan/torux && cd torux
+pip install .
+torux solve examples/quasr_0000954.json
+```
+
+```
+surface                verified: the solver's check and an independent evaluator agree
+toroidal flux          0.069106905814 Wb
+rotational transform   -0.0975229741144
+radii                  major 0.999994679 m, minor 0.150000523 m, aspect ratio 6.66661
+volume                 0.444132929 m^3
+Fourier series         M, N = 48, 32, with 2 field periods
+field across it        1.1e-15 of |B| (the solver's own check)
+independent check      3.3e-15 of |B| across it, and the same flux to within 8e-16
+time                   0.7 s
+```
+
+The first run compiles for up to a minute. After that, seconds.
+
+```python
+import torux
+
+s = torux.solve("coils.json", minor_radius=0.15)   # or flux=0.07 (Wb), volume=0.44 (m³), largest=True
+print(s)                                 # what it found and how it was checked, or why there is no surface
+s.iota, s.volume, s.aspect_ratio         # the numbers
+s.save("input.mine")                     # a VMEC input: VMEC, VMEC++, DESC and SIMSOPT read it
+s.plot("mine.png")                       # the picture below
+s.boozer().quasisymmetry                 # |B| in Boozer angles, and how far it is from quasi-symmetry
+
+torux.check("coils.json", "wout_other.nc")    # a surface from another code: how much of the field crosses it
+torux.many(files, table="answers.csv")        # a folder of designs, one row each
+```
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/plot-dark.png">
+    <img src="https://raw.githubusercontent.com/philippbogdan/torux/main/visuals/plot-light.png" width="760" alt="What s.plot draws for the surface above: on the left the flux surface as a green torus, shaded by the strength of the field on it, threaded through its four copper coils. On the right are its cross-sections at three toroidal angles, an ellipse lying flat, a rounded triangle and an ellipse standing upright, and the scale of the field strength, about 0.9 to 1.1 tesla.">
+  </picture>
+</p>
+
+Nothing to tune: no resolution, no tolerance, no starting guess. The coils are a file (SIMSOPT and QUASR JSON, MAKEGRID, FOCUS, permanent magnets, wireframes, a tokamak's coils), a QUASR design by its number, or a SIMSOPT or DESC object you already hold. [Usage](https://github.com/philippbogdan/torux/blob/main/docs/usage.md) and [formats](https://github.com/philippbogdan/torux/blob/main/docs/formats.md).
+
+## Credit
+
+Used torux? Say so, so the next person finds it:
+
+> Flux surfaces computed with [torux](https://github.com/philippbogdan/torux).
+
+```bibtex
+@software{bogdan2026torux,
+  author = {Bogdan, Philipp},
+  title  = {torux: vacuum flux surfaces at the limit of double-precision arithmetic},
+  year   = {2026},
+  url    = {https://github.com/philippbogdan/torux}
+}
+```
+
+Public domain, [CC0 1.0](https://github.com/philippbogdan/torux/blob/main/LICENSE), all but the picture of the twelve machines: six of them are drawn from files under GPL, LGPL and CC BY licences, and those renderings stay under their sources' terms. The coil sets torux was run on are other people's work, under their own licences: [credits](https://github.com/philippbogdan/torux/blob/main/NOTICE.md).

torux-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torux"
+version = "0.1.0"
+description = "Vacuum magnetic field and flux surfaces of coils and magnets for toroidal confinement, at the limit of double-precision arithmetic."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "CC0-1.0" }
+authors = [{ name = "Philipp Bogdan" }]
+keywords = ["stellarator", "plasma physics", "magnetic confinement", "flux surfaces", "fusion"]
+dependencies = [
+    "numpy>=2.4",
+    "scipy>=1.18",
+    "jax>=0.9",
+    "numba>=0.65",
+    "mpmath>=1.3",
+    "threadpoolctl>=3.1",
+]
+
+[project.optional-dependencies]
+hdf5 = ["h5py>=3.10"]
+plot = ["matplotlib>=3.9"]
+all = ["h5py>=3.10", "matplotlib>=3.9"]
+test = ["pytest>=8", "pandas>=2", "pyarrow>=15"]
+
+[project.urls]
+Repository = "https://github.com/philippbogdan/torux"
+
+[project.scripts]
+torux = "torux.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not slow'"
+markers = ["slow: takes minutes (the certificates); run with -m slow"]

torux-0.1.0/setup.cfg

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