Merge pull request #258 from dstansby/joss-paper

Merge accepted JOSS paper

doc/source/changes.rst

@@ -3,9 +3,12 @@
 Changelog
 =========
 
-0.6.2
+0.6.3
 -----
+This release contains the source for the accepted JOSS paper describing pfsspy.
 
+0.6.2
+-----
 This release includes several small fixes in response to a review of pfsspy
 for the Journal of Open Source Software. Thanks to Matthieu Ancellin and
 Simon Birrer for their helpful feedback!

joss-paper/paper.bib

@@ -0,0 +1,165 @@
+@article{Altschuler1969,
+  title = {Magnetic Fields and the Structure of the Solar Corona},
+  author = {Altschuler, Martin D. and Newkirk, Gordon},
+  year = {1969},
+  month = sep,
+  volume = {9},
+  pages = {131--149},
+  issn = {1573-093X},
+  doi = {10.1007/BF00145734},
+  journal = {Solar Physics},
+  number = {1}
+}
+
+@article{Schatten1969,
+  title = {A Model of Interplanetary and Coronal Magnetic Fields},
+  author = {Schatten, Kenneth H. and Wilcox, John M. and Ness, Norman F.},
+  year = {1969},
+  month = mar,
+  volume = {6},
+  pages = {442--455},
+  issn = {0038-0938},
+  doi = {10.1007/BF00146478},
+  journal = {Solar Physics}
+}
+
+@article{Badman2020,
+  title = {Magnetic {{Connectivity}} of the {{Ecliptic Plane}} within 0.5 Au: {{Potential Field Source Surface Modeling}} of the {{First Parker Solar Probe Encounter}}},
+  author = {Badman, Samuel T. and Bale, Stuart D. and Oliveros, Juan C. Mart{\'i}nez and Panasenco, Olga and Velli, Marco and Stansby, David and {Buitrago-Casas}, Juan C. and R{\'e}ville, Victor and Bonnell, John W. and Case, Anthony W. and de Wit, Thierry Dudok and Goetz, Keith and Harvey, Peter R. and Kasper, Justin C. and Korreck, Kelly E. and Larson, Davin E. and Livi, Roberto and MacDowall, Robert J. and Malaspina, David M. and Pulupa, Marc and Stevens, Michael L. and Whittlesey, Phyllis L.},
+  year = {2020},
+  month = feb,
+  volume = {246},
+  pages = {23},
+  issn = {0067-0049},
+  doi = {10.3847/1538-4365/ab4da7},
+  number = {2},
+  journal = {The Astrophysical Journal Supplement Series}
+}
+
+@article{Stansby2020,
+  title = {Directly Comparing Coronal and Solar Wind Elemental Fractionation},
+  author = {Stansby, D. and Baker, D. and Brooks, D. H. and Owen, C. J.},
+  year = {2020},
+  month = jun,
+  publisher = {{EDP Sciences}},
+  issn = {0004-6361, 1432-0746},
+  doi = {10.1051/0004-6361/202038319},
+  journal = {Astronomy \& Astrophysics},
+  language = {en}
+}
+
+@article{Maguire2020,
+  title = {Evolution of the {{Alfv\'en Mach}} Number Associated with a Coronal Mass Ejection Shock},
+  author = {Maguire, Ciara A. and Carley, Eoin P. and McCauley, Joseph and Gallagher, Peter T.},
+  year = {2020},
+  month = jan,
+  volume = {633},
+  pages = {A56},
+  issn = {0004-6361, 1432-0746},
+  doi = {10.1051/0004-6361/201936449},
+  copyright = {\textcopyright{} ESO 2020},
+  journal = {Astronomy \& Astrophysics},
+  language = {en}
+}
+
+@article{Bobra2020,
+  title = {A {{Survey}} of {{Computational Tools}} in {{Solar Physics}}},
+  author = {Bobra, Monica G. and Mumford, Stuart J. and Hewett, Russell J. and Christe, Steven D. and Reardon, Kevin and Savage, Sabrina and Ireland, Jack and Pereira, Tiago M. D. and Chen, Bin and {P{\'e}rez-Su{\'a}rez}, David},
+  year = {2020},
+  month = apr,
+  volume = {295},
+  pages = {57},
+  issn = {1573-093X},
+  doi = {10.1007/s11207-020-01622-2},
+  journal = {Solar Physics},
+  language = {en},
+  number = {4}
+}
+
+@article{Bale2019,
+  title = {Highly Structured Slow Solar Wind Emerging from an Equatorial Coronal Hole},
+  author = {Bale, S. D. and Badman, S. T. and Bonnell, J. W. and Bowen, T. A. and Burgess, D. and Case, A. W. and Cattell, C. A. and Chandran, B. D. G. and Chaston, C. C. and Chen, C. H. K. and Drake, J. F. and de Wit, T. Dudok and Eastwood, J. P. and Ergun, R. E. and Farrell, W. M. and Fong, C. and Goetz, K. and Goldstein, M. and Goodrich, K. A. and Harvey, P. R. and Horbury, T. S. and Howes, G. G. and Kasper, J. C. and Kellogg, P. J. and Klimchuk, J. A. and Korreck, K. E. and Krasnoselskikh, V. V. and Krucker, S. and Laker, R. and Larson, D. E. and MacDowall, R. J. and Maksimovic, M. and Malaspina, D. M. and {Martinez-Oliveros}, J. and McComas, D. J. and {Meyer-Vernet}, N. and Moncuquet, M. and Mozer, F. S. and Phan, T. D. and Pulupa, M. and Raouafi, N. E. and Salem, C. and Stansby, D. and Stevens, M. and Szabo, A. and Velli, M. and Woolley, T. and Wygant, J. R.},
+  year = {2019},
+  month = dec,
+  volume = {576},
+  pages = {237--242},
+  issn = {1476-4687},
+  doi = {10.1038/s41586-019-1818-7},
+  journal = {Nature},
+  language = {en},
+  number = {7786}
+}
+
+@article{TheSunPyCommunity2020,
+  title = {The {{SunPy Project}}: {{Open Source Development}} and {{Status}} of the {{Version}} 1.0 {{Core Package}}},
+  shorttitle = {The {{SunPy Project}}},
+  author = {{The SunPy Community} and Barnes, Will T. and Bobra, Monica G. and Christe, Steven D. and Freij, Nabil and Hayes, Laura A. and Ireland, Jack and Mumford, Stuart and {Perez-Suarez}, David and Ryan, Daniel F. and Shih, Albert Y. and Chanda, Prateek and Glogowski, Kolja and Hewett, Russell and Hughitt, V. Keith and Hill, Andrew and Hiware, Kaustubh and Inglis, Andrew and Kirk, Michael S. F. and Konge, Sudarshan and Mason, James Paul and Maloney, Shane Anthony and Murray, Sophie A. and Panda, Asish and Park, Jongyeob and Pereira, Tiago M. D. and Reardon, Kevin and Savage, Sabrina and Sip{\H o}cz, Brigitta M. and Stansby, David and Jain, Yash and Taylor, Garrison and Yadav, Tannmay and {Rajul} and Dang, Trung Kien},
+  year = {2020},
+  month = feb,
+  volume = {890},
+  pages = {68},
+  publisher = {{American Astronomical Society}},
+  issn = {0004-637X},
+  doi = {10.3847/1538-4357/ab4f7a},
+  journal = {The Astrophysical Journal},
+  language = {en},
+  number = {1}
+}
+
+@article{Mumford2020a,
+  title = {{{SunPy}}: {{A Python}} Package for {{Solar Physics}}},
+  shorttitle = {{{SunPy}}},
+  author = {Mumford, Stuart J. and Freij, Nabil and Christe, Steven and Ireland, Jack and Mayer, Florian and Hughitt, V. Keith and Shih, Albert Y. and Ryan, Daniel F. and Liedtke, Simon and {P{\'e}rez-Su{\'a}rez}, David and Chakraborty, Pritish and K, Vishnunarayan and Inglis, Andrew and Pattnaik, Punyaslok and Sip{\H o}cz, Brigitta and Sharma, Rishabh and Leonard, Andrew and Stansby, David and Hewett, Russell and Hamilton, Alex and Hayes, Laura and Panda, Asish and Earnshaw, Matt and Choudhary, Nitin and Kumar, Ankit and Chanda, Prateek and Haque, Md Akramul and Kirk, Michael S. and Mueller, Michael and Konge, Sudarshan and Srivastava, Rajul and Jain, Yash and Bennett, Samuel and Baruah, Ankit and Barnes, Will and Charlton, Michael and Maloney, Shane and Chorley, Nicky and Himanshu and Modi, Sanskar and Mason, James Paul and Naman9639 and Rozo, Jose Ivan Campos and Manley, Larry and Chatterjee, Agneet and Evans, John and Malocha, Michael and Bobra, Monica G. and Ghosh, Sourav and Airmansmith97 and Sta{\'n}czak, Dominik and Visscher, Ruben De and Verma, Shresth and Agrawal, Ankit and Buddhika, Dumindu and Sharma, Swapnil and Park, Jongyeob and Bates, Matt and Goel, Dhruv and Taylor, Garrison and Cetusic, Goran and Jacob and Inchaurrandieta, Mateo and Dacie, Sally and Dubey, Sanjeev and Sharma, Deepankar and Bray, Erik M. and Rideout, Jai Ram and Zahniy, Serge and Meszaros, Tomas and Bose, Abhigyan and Chicrala, Andr{\'e} and Ankit and Guennou, Chlo{\'e} and D'Avella, Daniel and Williams, Daniel and Ballew, Jordan and Murphy, Nick and Lodha, Priyank and Robitaille, Thomas and Krishan, Yash and Hill, Andrew and Eigenbrot, Arthur and Mampaey, Benjamin and Wiedemann, Bernhard M. and Molina, Carlos and Ke{\c s}kek, Duygu and Habib, Ishtyaq and Letts, Joseph and Baz{\'a}n, Juanjo and Arbolante, Quinn and Gomillion, Reid and Kothari, Yash and Sharma, Yash and Stevens, Abigail L. and {Price-Whelan}, Adrian and Mehrotra, Ambar and Kustov, Arseniy and Stone, Brandon and nil Dang, Trung Kien and Arias, Emmanuel and Dover, Fionnlagh Mackenzie and Verstringe, Freek and Kumar, Gulshan and Mathur, Harsh and Babuschkin, Igor and Wimbish, Jaylen and {Buitrago-Casas}, Juan Camilo and Krishna, Kalpesh and Hiware, Kaustubh and Mangaonkar, Manas and Mendero, Matthew and Schoentgen, Micka{\"e}l and Gyenge, Norbert G. and Streicher, Ole and Mekala, Rajasekhar Reddy and Mishra, Rishabh and Srikanth, Shashank and Jain, Sarthak and Yadav, Tannmay and Wilkinson, Tessa D. and d Pereira, Tiago M. and Agrawal, Yudhik and Jamescalixto and Yasintoda and Murray, Sophie A.},
+  year = {2020},
+  month = feb,
+  volume = {5},
+  pages = {1832},
+  issn = {2475-9066},
+  doi = {10.21105/joss.01832},
+  journal = {Journal of Open Source Software},
+  language = {en},
+  number = {46}
+}
+
+@article{TheAstropyCollaboration2018,
+  title = {The {{Astropy Project}}: {{Building}} an {{Open}}-Science {{Project}} and {{Status}} of the v2.0 {{Core Package}}},
+  author = {{The Astropy Collaboration} and {Price-Whelan}, A. M. and Sip{\H o}cz, B. M. and G{\"u}nther, H. M. and Lim, P. L. and Crawford, S. M. and Conseil, S. and Shupe, D. L. and Craig, M. W. and Dencheva, N. and Ginsburg, A. and VanderPlas, J. T. and Bradley, L. D. and {P{\'e}rez-Su{\'a}rez}, D. and {de Val-Borro}, M. and Aldcroft, T. L. and Cruz, K. L. and Robitaille, T. P. and Tollerud, E. J. and Ardelean, C. and Babej, T. and Bach, Y. P. and Bachetti, M. and Bakanov, A. V. and Bamford, S. P. and Barentsen, G. and Barmby, P. and Baumbach, A. and Berry, K. L. and Biscani, F. and Boquien, M. and Bostroem, K. A. and Bouma, L. G. and Brammer, G. B. and Bray, E. M. and Breytenbach, H. and Buddelmeijer, H. and Burke, D. J. and Calderone, G. and Rodr{\'i}guez, J. L. Cano and Cara, M. and Cardoso, J. V. M. and Cheedella, S. and Copin, Y. and Corrales, L. and Crichton, D. and D'Avella, D. and Deil, C. and Depagne, {\'E}. and Dietrich, J. P. and Donath, A. and Droettboom, M. and Earl, N. and Erben, T. and Fabbro, S. and Ferreira, L. A. and Finethy, T. and Fox, R. T. and Garrison, L. H. and Gibbons, S. L. J. and Goldstein, D. A. and Gommers, R. and Greco, J. P. and Greenfield, P. and Groener, A. M. and Grollier, F. and Hagen, A. and Hirst, P. and Homeier, D. and Horton, A. J. and Hosseinzadeh, G. and Hu, L. and Hunkeler, J. S. and Ivezi{\'c}, {\v Z}. and Jain, A. and Jenness, T. and Kanarek, G. and Kendrew, S. and Kern, N. S. and Kerzendorf, W. E. and Khvalko, A. and King, J. and Kirkby, D. and Kulkarni, A. M. and Kumar, A. and Lee, A. and Lenz, D. and Littlefair, S. P. and Ma, Z. and Macleod, D. M. and Mastropietro, M. and McCully, C. and Montagnac, S. and Morris, B. M. and Mueller, M. and Mumford, S. J. and Muna, D. and Murphy, N. A. and Nelson, S. and Nguyen, G. H. and Ninan, J. P. and N{\"o}the, M. and Ogaz, S. and Oh, S. and Parejko, J. K. and Parley, N. and Pascual, S. and Patil, R. and Patil, A. A. and Plunkett, A. L. and Prochaska, J. X. and Rastogi, T. and Janga, V. Reddy and Sabater, J. and Sakurikar, P. and Seifert, M. and Sherbert, L. E. and {Sherwood-Taylor}, H. and Shih, A. Y. and Sick, J. and Silbiger, M. T. and Singanamalla, S. and Singer, L. P. and Sladen, P. H. and Sooley, K. A. and Sornarajah, S. and Streicher, O. and Teuben, P. and Thomas, S. W. and Tremblay, G. R. and Turner, J. E. H. and Terr{\'o}n, V. and van Kerkwijk, M. H. and {de la Vega}, A. and Watkins, L. L. and Weaver, B. A. and Whitmore, J. B. and Woillez, J. and Zabalza, V.},
+  year = {2018},
+  month = aug,
+  volume = {156},
+  pages = {123},
+  publisher = {{IOP Publishing}},
+  issn = {1538-3881},
+  doi = {10.3847/1538-3881/aabc4f},
+  journal = {The Astronomical Journal},
+  number = {3}
+}
+
+@article{Freeland1998,
+  title = {Data {{Analysis}} with the {{SolarSoft System}}},
+  author = {Freeland, S.L. and Handy, B.N.},
+  year = {1998},
+  month = oct,
+  volume = {182},
+  pages = {497--500},
+  issn = {1573-093X},
+  doi = {10.1023/A:1005038224881},
+  journal = {Solar Physics},
+  language = {en},
+  number = {2}
+}
+
+@article{Ballegooijen2000,
+  title = {Mean {{Field Model}} for the {{Formation}} of {{Filament Channels}} on the {{Sun}}},
+  author = {van Ballegooijen, A. A. and Priest, E. R. and Mackay, D. H.},
+  year = {2000},
+  month = aug,
+  volume = {539},
+  pages = {983},
+  publisher = {{IOP Publishing}},
+  issn = {0004-637X},
+  doi = {10.1086/309265},
+  journal = {The Astrophysical Journal},
+  language = {en},
+  number = {2}
+}

joss-paper/paper.md

@@ -0,0 +1,96 @@
+---
+title: 'pfsspy: A Python package for potential field source surface modelling'
+tags:
+  - Python
+  - Astronomy
+  - Solar physics
+authors:
+  - name: David Stansby
+    orcid: 0000-0002-1365-1908
+    affiliation: 1
+  - name: Anthony Yeates
+    orcid: 0000-0002-2728-4053
+    affiliation: 2
+  - name: Samuel T. Badman
+    orcid: 0000-0002-6145-436X
+    affiliation: "3, 4"
+affiliations:
+ - name: Mullard Space Science Laboratory, University College London, Holmbury St. Mary, Surrey RH5 6NT, UK
+   index: 1
+ - name: Department of Mathematical Sciences, Durham University, Durham, DH1 3LE, UK
+   index: 2
+ - name: Physics Department, University of California, Berkeley, CA 94720-7300, USA
+   index: 3
+ - name: Space Sciences Laboratory, University of California, Berkeley, CA 94720-7450, USA
+   index: 4
+date: 2 October 2020
+bibliography: paper.bib
+---
+
+# Summary
+Magnetic fields play a crucial role in the dynamics and evolution of our Sun
+and other stars. A common method used to model the magnetic fields in solar and
+stellar atmospheres is the potential field source surface (PFSS) model [@Altschuler1969; @Schatten1969].
+The PFSS equations assume that there is zero electrical current in the domain
+of interest, leading to the equations
+\begin{equation}
+	\nabla \cdot \mathbf{B} = 0;~~~\nabla \times \mathbf{B} = 0
+\end{equation}
+
+These are solved in a spherical shell between the surface of the star and
+a configurable outer radius called the 'source surface'. Boundary
+conditions are given by the user specified radial component of $\mathbf{B}$ on
+the inner boundary and the imposed condition of a purely radial field on the source
+surface, which mimics the effect of the escaping stellar wind.
+
+Historically, either custom implementations or the `pfsspack`^[https://www.lmsal.com/~derosa/pfsspack/,
+which forms part of the larger `SolarSoft` library for solar physics [@Freeland1998],
+written in Interactive Data Language (IDL).]
+IDL library have been used to perform PFSS extrapolations. As Python has become a
+major programming language within the solar physics and wider astronomy
+community [@Bobra2020], there is a need to provide well documented and tested
+functionality to perform PFSS extrapolations within the Python ecosystem,
+a niche that `pfsspy` fills.
+
+
+# pfsspy
+`pfsspy` is a Python package for solving the PFSS equations, and carrying out
+other common related tasks such as tracing magnetic field lines through the
+solution, importing various magnetic field data sources, and visualising all of
+this data.
+
+The PFSS code implements a finite difference solver, based on the method of
+@Ballegooijen2000. Given a 2D map of the radial magnetic field on the inner
+boundary, the magnetic vector potential is calculated on a 3D grid equally
+spaced in $\sin($latitude$)$, longitude, and $\ln($radius$)$. This method is
+tailored in order to achieve $\nabla \times \mathbf{B} = 0$ to machine
+precision. More details on the exact numerical scheme are given in the online
+documentation^[https://pfsspy.readthedocs.io].
+
+
+## Integration
+
+`pfsspy` is designed to closely integrate with other packages in the
+astronomical and solar physics Python ecosystems. Coordinate aware input and
+output maps are created with the sunpy package [@Mumford2020a; @TheSunPyCommunity2020],
+and `pfsspy` is fully integrated with the coordinate and unit framework
+present in astropy [@TheAstropyCollaboration2018]. This makes it easy to
+combine magnetic fields and field lines calculated in `pfsspy` with other data
+sources. As an example, \autoref{fig} shows magnetic field lines overplotted
+on an extreme-ultraviolet image of a large active region on the Sun.
+
+![An image of the Sun taken by SDO/AIA at 193 angstroms, with selected magnetic field lines traced through a PFSS solution overplotted in white. The PFSS solution and field line tracing were done with `pfsspy`, with a Global Oscillations Network Group (GONG) photospheric magnetogram as input and a source surface at 2.5 solar radii. Although only selected field lines are shown, the magnetic field is solved over the whole Sun.\label{fig}](pfsspy.pdf)
+
+The solar physics community has already made use of `pfsspy` in a number of
+works, from interpreting observations from Parker Solar Probe [@Bale2019; @Badman2020],
+investigating the structure of coronal mass ejections [@Maguire2020], and
+drawing links between the Sun and the solar wind [@Stansby2020]. We hope that
+it continues to provide a useful resource for the community in the future.
+
+
+# Acknowledgements
+
+David Stansby acknowledges STFC grants ST/N504336/1 and ST/S000240/1.
+Anthony Yeates acknowledges STFC grant ST/S000321/1.
+
+# References