Merge pull request PrincetonUniversity#209 from missing-user/readme-4…

…04-fix

Readme 404 fix

.github/workflows/doxygen.yml

@@ -19,7 +19,13 @@ jobs:
     steps:
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
     - uses: actions/checkout@v2
-
+
+    # Validate CITATION.cff
+    - name: CITATION.cff to spec_refs.bib
+      run: |
+            pip install --user pyyaml cffconvert==2.0.0 
+            cffconvert --validate
+
     # run doxygen
     - name: Doxygen Action
       uses: mattnotmitt/[email protected]
@@ -28,7 +34,9 @@ jobs:
 
     - name: Copy Pdf
       working-directory: ${{ github.workspace }}
-      run: sudo cp ./docs/latex/refman.pdf ./docs/html/SPEC_manual.pdf
+      run: |
+            sudo cp ./docs/latex/refman.pdf ./docs/html/SPEC_manual.pdf  
+            sudo cp ./docs/SPEC_flowchart.pdf ./docs/html/SPEC_flowchart.pdf
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3

CITATION.cff

@@ -0,0 +1,171 @@
+cff-version: 1.2.0
+title: Stepped Pressure Equilibrium Code (SPEC)
+message: If you use SPEC in your research, please cite the following works.
+type: software
+contact:
+  - family-names: Hudson
+    given-names: Stuart
+    email: [email protected]
+    affiliation: Princeton Plasma Physics Laboratory
+    orcid: "https://orcid.org/0000-0003-1530-2733"
+authors:
+  - family-names: Hudson
+    given-names: Stuart
+    email: [email protected]
+    affiliation: Princeton Plasma Physics Laboratory
+    orcid: "https://orcid.org/0000-0003-1530-2733"
+  - family-names: Schilling
+    given-names: Jonathan
+    affiliation: Max-Planck Institute for Plasma Physics
+    orcid: https://orcid.org/0000-0002-6363-6554
+  - family-names: Baillod
+    given-names: Antoine
+    affiliation: Columbia University
+    orcid: https://orcid.org/0000-0003-0352-9180
+  - family-names: Qu
+    given-names: Zhisong
+    affiliation: Nanyang Technological University
+    orcid: https://orcid.org/0000-0003-4628-6983
+  - family-names: Loizu
+    given-names: Joaquim
+    affiliation: Federal Institute of Technology Lausanne (EPFL)
+    orcid: https://orcid.org/0000-0002-4862-7393
+  - family-names: Medasani
+    given-names: Bharat
+    affiliation: New Mexico State University
+  - family-names: Smiet
+    given-names: Christopher Berg
+    orcid: https://orcid.org/0000-0002-7803-7685
+    affiliation: Federal Institute of Technology Lausanne (EPFL)
+  - family-names: Zhu
+    given-names: Caoxiang
+    affiliation: University of Science and Technology of China
+    orcid: https://orcid.org/0000-0003-2337-3232
+  - family-names: Lazerson
+    given-names: Samuel Aaron
+    affiliation: Princeton Plasma Physics Laboratory
+    orcid: https://orcid.org/0000-0001-8002-0121
+  - family-names: Breslau
+    given-names: Joshua
+    affiliation: Princeton Plasma Physics Laboratory
+    orcid: https://orcid.org/0000-0002-0649-4836
+identifiers:
+  - type: url
+    value: https://github.com/PrincetonUniversity/SPEC/releases/tag/v3.20
+    description: The GitHub URL for the SPEC v3.20 release
+repository-code: https://github.com/PrincetonUniversity/SPEC
+url: https://princetonuniversity.github.io/SPEC/
+abstract: >-
+  A code for calculating magnetohydrodynamic equilibria with
+  stepped pressure-profiles, by finding stationary points in
+  the MRxMHD energy functional.
+keywords:
+  - magnetohydrodynamics
+  - SPEC
+  - MRxMHD
+license: GPL-3.0
+commit: 5996ea6db8cea383c659fced8e6a2c24cd774642
+version: "3.20"
+date-released: "2022-07-01"
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Hudson
+      given-names: Stuart
+      email: [email protected]
+      affiliation: "Princeton Plasma Physics Laboratory"
+      orcid: "https://orcid.org/0000-0003-1530-2733"
+    - family-names: Dewar
+      given-names: R. L.
+      affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+    - family-names: Hole
+      given-names: M. J.
+      affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+    - family-names: Dennis
+      given-names: G.
+      affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+    - family-names: McGann
+      given-names: M.
+      affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+    - family-names: von Nessi
+      given-names: G.
+      affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+    - family-names: Lazerson
+      given-names: Samuel Aaron
+      affiliation: "Princeton Plasma Physics Laboratory"
+      orcid: https://orcid.org/0000-0001-8002-0121
+  title: Computation of multi-region relaxed magnetohydrodynamic equilibria
+  journal: Phys. Plasmas
+  volume: "19"
+  issue: "11"
+  year: 2012
+  doi: 10.1063/1.4765691
+  url: "https://doi.org/10.1063/1.4765691"
+references:
+  - type: article
+    authors:
+      - family-names: Hudson
+        given-names: Stuart
+        email: [email protected]
+        affiliation: "Princeton Plasma Physics Laboratory"
+        orcid: "https://orcid.org/0000-0003-1530-2733"
+      - family-names: Dewar
+        given-names: R. L.
+        affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+      - family-names: Hole
+        given-names: M. J.
+        affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+      - family-names: Dennis
+        given-names: G.
+        affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+      - family-names: McGann
+        given-names: M.
+        affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+      - family-names: von Nessi
+        given-names: G.
+        affiliation: "Plasma Research Laboratory, Research School of Physics & Engineering, The Australian National University, Canberra ACT 0200, Australia"
+      - family-names: Lazerson
+        given-names: Samuel Aaron
+        affiliation: "Princeton Plasma Physics Laboratory"
+        orcid: https://orcid.org/0000-0001-8002-0121
+    title: Computation of multi-region relaxed magnetohydrodynamic equilibria
+    journal: Phys. Plasmas
+    volume: "19"
+    issue: "11"
+    year: 2012
+    doi: 10.1063/1.4765691
+    url: "https://doi.org/10.1063/1.4765691"
+  - type: article
+    authors:
+      - family-names: Hudson
+        given-names: Stuart R.
+        orcid: https://orcid.org/0000-0003-1530-2733
+      - family-names: Loizu
+        given-names: Joaquim
+        orcid: https://orcid.org/0000-0002-4862-7393
+      - family-names: Zhu
+        given-names: Caoxiang
+        orcid: https://orcid.org/0000-0003-2337-3232
+      - family-names: Qu
+        given-names: Zhisong
+        orcid: https://orcid.org/0000-0003-4628-6983
+      - family-names: Nührenberg
+        given-names: Carolin
+      - family-names: Lazerson
+        given-names: Samuel A.
+        orcid: https://orcid.org/0000-0001-8002-0121
+      - family-names: Smiet
+        given-names: Christopher Berg
+        orcid: https://orcid.org/0000-0002-7803-7685
+      - family-names: Hole
+        given-names: Matthew J.
+        orcid: https://orcid.org/0000-0002-9550-8776
+    title: "Free-boundary MRxMHD equilibrium calculations using the stepped-pressure equilibrium code"
+    journal: "Plasma Physics and Controlled Fusion"
+    volume: "62"
+    issue: "8"
+    pages: "084002"
+    year: 2020
+    doi: "10.1088/1361-6587/ab9a61"
+    url: "https://dx.doi.org/10.1088/1361-6587/ab9a61"
+

Doxyfile

@@ -856,7 +856,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = README.md Compile.md src
+INPUT                  = README.md compilation_instructions.md src docs/Citelist.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

README.md

@@ -1,13 +1,19 @@
-# The Stepped Pressure Equilibrium Code
+ ![SPEC logo](SPEC_97x55.png)
+# The Stepped Pressure Equilibrium Code 
 
-All relevant publications and presentations are given on the [MRxMHD website](http://w3.pppl.gov/~shudson/Spec/spec.html).
+SPEC solves 3D magnetohydrodynamic (MHD) equilibria with stepped-pressure profiles. This powerful description doesn't artificially restrict the solution to nested flux surfaces, and admits simulations with islands and chaotic regions. It is a spectral-element code, that finds minimal-plasma-energy states by extremizing the multi-region, relaxed-MHD (MRxMHD) energy functional. 
 
-A BibTex file is available: [spec_refs.bib](https://raw.githubusercontent.com/PrincetonUniversity/SPEC/master/spec_refs.bib).
+- There is a [brief description of SPEC](https://theory.pppl.gov/research/research.php?rid=10#h5) on the Princeton Plasma Physics Laboratory [Theory Department website](https://theory.pppl.gov/). 
+- An overview of the algorithm is given in a [Flow Chart](https://princetonuniversity.github.io/SPEC/docs/SPEC_flowchart.pdf).
+- A list of publications using SPEC are in our [bibliography section](https://princetonuniversity.github.io/SPEC/citelist)
+- Please direct questions/suggestions to [Stuart Hudson](mailto:[email protected]?subject=spec).
+
+## Citation
+If you use SPEC in your research, please cite it appropriately using the "Cite this repository" button on the right of the [SPEC GitHub Repository](https://github.com/PrincetonUniversity/SPEC) or the [CITATION.cff](https://github.com/PrincetonUniversity/SPEC/blob/master/CITATION.cff) file. 
+
+## Installation
+Instructions for compiling and testing SPEC are in [compilation_instructions.md](compilation_instructions.md).
+
+## Documentation
+Online documentation for SPEC is available on [Github pages](https://princetonuniversity.github.io/SPEC/) or in PDF form at [SPEC_manual.pdf](https://princetonuniversity.github.io/SPEC/SPEC_manual.pdf).
 
-* There is also a [brief description of SPEC](http://theory.pppl.gov/research/research.php?rid=10#h5)
-  on the Princeton Plasma Physics Laboratory [Theory Department website](http://theory.pppl.gov/).
-* An overview of the algorithm is given in a [Flow Chart](http://w3.pppl.gov/~shudson/Spec/SpecFlowchart.pdf).
-* Please direct questions/suggestions to [Stuart Hudson](mailto:[email protected]?subject=spec).
-* Online documentation for SPEC is available on [Github pages](https://princetonuniversity.github.io/SPEC/).  
-  A PDF version of this manual is available in [SPEC_manual.pdf](https://princetonuniversity.github.io/SPEC/SPEC_manual.pdf).
-* Instructions for compiling and testing SPEC are in [Compile.md](https://github.com/PrincetonUniversity/SPEC/blob/master/Compile.md).

docs/Citelist.md

@@ -0,0 +1,16 @@
+List of papers using spec 
+(Citations that aren't explicitly referenced, don't appear in the bibliography, so we list them all here.)
+
+\cite y2015_hanson
+\cite y2017_zhu
+\cite y2016_loizu
+\cite y2021_baillod
+\cite y2016_loizu_1
+\cite y2015_loizu_1
+\cite y2015_loizu
+\cite y2020_loizu
+\cite y2023_loizu
+\cite y2017_loizu
+\cite y2023_baillod
+\cite y2019_loizu
+\cite y2024_liu