{"id":21183167,"url":"https://github.com/jonathanschilling/educational_vmec","last_synced_at":"2026-01-02T15:08:17.413Z","repository":{"id":53085534,"uuid":"352945866","full_name":"jonathanschilling/educational_VMEC","owner":"jonathanschilling","description":"Serial VMEC for educational purposes (e.g. understanding the algorithms etc.)","archived":false,"fork":false,"pushed_at":"2025-01-20T14:23:30.000Z","size":157829,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-20T15:30:49.175Z","etag":null,"topics":["angle-constraint","nestor","stellarator","stellarators","tokamak","tokamaks","vmec"],"latest_commit_sha":null,"homepage":"https://jonathanschilling.github.io/educational_VMEC/","language":"Fortran","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonathanschilling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-30T09:35:00.000Z","updated_at":"2025-01-20T14:23:01.000Z","dependencies_parsed_at":"2023-10-05T10:54:53.764Z","dependency_job_id":"a8c87bd6-7a2e-4b69-bfc9-ecfd5675ca7c","html_url":"https://github.com/jonathanschilling/educational_VMEC","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanschilling%2Feducational_VMEC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanschilling%2Feducational_VMEC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanschilling%2Feducational_VMEC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathanschilling%2Feducational_VMEC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonathanschilling","download_url":"https://codeload.github.com/jonathanschilling/educational_VMEC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243639400,"owners_count":20323505,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angle-constraint","nestor","stellarator","stellarators","tokamak","tokamaks","vmec"],"created_at":"2024-11-20T17:59:29.411Z","updated_at":"2026-01-02T15:08:17.377Z","avatar_url":"https://github.com/jonathanschilling.png","language":"Fortran","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Educational VMEC\n\nThis is a heavily stripped-down version of the serial implementation of VMEC 8.52.\nIt is forked from the `v251` branch of the [STELLOPT](https://github.com/PrincetonUniversity/STELLOPT) repository.\n\nThe goal of this project is to have a version of VMEC\nwhich only computes the Stellarator MHD equilibrium and nothing more.\n\nThe `cmake` build system for stand-alone VMEC is borrowed\nfrom [hiddenSymmetries/VMEC2000](https://github.com/hiddenSymmetries/VMEC2000)\nand from [ORNL-Fusion/LIBSTELL](https://github.com/ORNL-Fusion/LIBSTELL).\n\n## Building\nRequired packages on Debian stable are:\n`cmake`, `gfortran`, `libnetcdff-dev`, `libblas-dev`, `liblapack-dev`, `libfftw3-dev`\n\nYou need to download this repository and the included `json-fortran`.\nThe easiest way to do this is via a recursive `git clone`:\n\n```bash\n\u003e git clone --recursive https://github.com/jonathanschilling/educational_VMEC.git\n```\n\nIgnore warnings about missing access to `src/vac2` and `src/vac3`.\nAfter cloning, the `json-fortran` directory is somewhat messed up and you need to fix that:\n\n```bash\n\u003e cd educational_VMEC/json-fortran\n\u003e git restore --staged .\n\u003e git checkout .\n\u003e cd ..\n```\n\nThis is a fairly standard CMake setup, if you are used to it.\nHere is how it works:\n * Create a directory `build` in the main folder: `mkdir build`\n * Go into the `build` directory: `cd build`\n * Run CMake: `cmake ..`\n * Execute the actual build process: `make` (optional multi-threaded build: `make -j`)\n * The VMEC executable `xvmec` is then located in `build/bin` with respect to the main folder.\n \n## Example Execution\n * Change into the `test` dir: `cd test`\n * Run the [Solov'ev test case](https://princetonuniversity.github.io/FOCUS/notes/Coil_design_codes_benchmark.html#Equiblirium--): `../build/bin/xvmec input.solovev`\n\n## Debug Output\n\nThe [`dbgout`](src/dbgout.f90) module allows to (optionally) write a bunch of data from within the code into separate JSON files.\nWriting these additional quantities is disabled by default and can be enabled by logical flags in the `INDATA` namelist.\nA full list of the available flags (ordered by module where they are used) is available in [vmec_input.f90](src/data/vmec_input.f90#L89).\nA folder named the same as the extension of the input file will be created.\nIn there, subfolders named after each of the enabled `dump_*` flags will be created.\nFor example, put `dump_forces=.true.` into `input.solovev` and the folder `solovev/forces/` will be created and JSON files will appear in there.\nIn each of these subfolders, JSON files will be created according to the following naming scheme:\n`forces_\u003cns\u003e_\u003citeration\u003e_\u003coccurence\u003e.\u003cextension\u003e.json` where\n- `ns` is the number of flux surfaces of the respective multi-grid step,\n- `iteration` is the iteration number printed to the screen and\n- `occurence` is a linear counter used in case the respective quantities need to get dumped more than once in the respective context (e.g. before and after some important subroutine call)\n\nAs a first start, I usually look at JSON files using the Firefox browser, which has a rather nice built-in JSON viewer.\nFor plotting, I have written a Python utility [`plot_dbg_json.py`](test/plot_dbg_json.py),\nwhich can plot the quantities from the JSON files produced by `educational_VMEC`.\n\nUse it as follows:\n1. to plot all quantities (at all flux surfaces) in a given JSON file:\n \n   ```\n   ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json\n   ```\n   \n2. the list of quantities to plot can be specified as follows (for quicker iterations, since plotting everything can take a while):\n\n    ```\n    ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json --quantities ru12\n    ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json --quantities ru12 zu12\n    ```\n   \n3. to plot a subset of flux surfaces (0-based indexing):\n \n   ```\n   ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json --surfaces 6\n   ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json --surfaces 0 5 14\n   ```\n   \n4. to plot a subset of quantities at a subset of surfaces:\n\n   ```\n   ../../plot_dbg_json.py forces_00015_000001_01.test.vmec.json --quantities ru12 zu12 --surfaces 6 7\n   ```\n\n## External NESTOR\nThe free-boundary part of VMEC is the Neumann Solver for Toroidal Systems (NESTOR).\nIts source code is in a separate folder [`NESTOR`](src/NESTOR).\nThe appropriate reference is https://doi.org/10.1016/0021-9991(86)90055-0 .\n\nThis version of NESTOR can be run stand-alone. It reads its inputs from a netCDF file and writes its outputs into another netCDF file.\nThe main executable of this stand-alone version of NESTOR is [`nestor_main.f90`](src/NESTOR/nestor_main.f90).\nThe input and output files are read and written in [`nestor_io.f90`](src/NESTOR/data/nestor_io.f90).\n\nThis version of VMEC can be configured to dump the corresponding input and output files, but still run the compiled-in version of NESTOR.\nThis is enabled via the logical flag `ldump_vacuum_ref` in [`funct3d.f90`](src/funct3d.f90).\n\nAlso, an external NESTOR implementation can be called instead of using the compiled-in version of NESTOR.\nThis is enabled via the logical flag `lexternal_nestor` in [`funct3d.f90`](src/funct3d.f90).\nThe corresponding system call to execute the external NESTOR implementation has to be specified in\n`nestor_executable` in [`funct3d.f90`](src/funct3d.f90).\n\n## Angle Constraint\nThe poloidal angle-like coordinate is a priori not uniquely defined and needs special care.\nThe version of VMEC from the STELLOPT repo had essentially two options for this.\nThey were alternatively compiled in via the preprocessor flag `_HBANGLE`.\n\n1. The Hirshman-Breslau explicit spectrally optimized Fourier series (see https://doi.org/10.1063/1.872954 for details) and\n2. an unknown mixture of several constraints of the `m=1` Fourier coefficients (the logical `lconm1` is true for this constraint).\n\nBy default, the `_HBANGLE` preprocessor flag is not active and thus, the \"old\" `m=1` constraint is active.\n\nThis version of VMEC has all preprocessor flags already expanded.\nIt became clear that it is nevertheless useful to have at least a vague idea of what parts of the code are related to the angle constraint.\nTherefore, those parts of VMEC related to the `m=1`constraint are marked to start with \n\n```Fortran\n! #ifndef _HBANGLE\n```\n\nand end with\n\n\n```Fortran\n! #end /* ndef _HBANGLE */\n```\n\nNote that the [original documentation](https://github.com/jonathanschilling/educational_VMEC/blob/master/vmec_info.md) states:\n\u003e THE POLOIDAL ANGLE IS DETERMINED BY MINIMIZING \u003cM\u003e = m\\*\\*2 S(m) , WHERE S(m) = Rm\\*\\*2 + Zm\\*\\*2 .\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanschilling%2Feducational_vmec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathanschilling%2Feducational_vmec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathanschilling%2Feducational_vmec/lists"}