JOSS Submission

.github/workflows/build_publish.yml

@@ -1,6 +1,8 @@
 name: Build/publish package
 
-on: push
+on: 
+  push:
+    branches-ignore: [joss]
 
 jobs:
   build_wheels:

.github/workflows/draft_joss.yml

@@ -0,0 +1,26 @@
+name: Draft JOSS
+on:
+    push:
+        branches: [joss]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: joss/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: joss/paper.pdf

joss/.gitignore

@@ -0,0 +1,5 @@
+# Ignore EPOCH files
+*.sdf
+deck.status
+o1.visit
+epoch2d.dat

joss/README.md

@@ -0,0 +1,25 @@
+# JOSS Submission
+
+This directory contains the paper and scripts for the submission to the Journal of Open Source Software
+
+- `paper.md`: Paper
+- `paper.bib`: bibliography
+- `generate_figures.py`: Generate the figures for the plot
+- `input.deck`: The EPOCH setup script used to generate the data for the figures
+- `Electric_Field_Ey.png`: A plot of a laser focusing in a vacuum of the 10th SDF file
+- `Electric_Field_Ey.gif`: The animation of a laser focusing in a vacuum
+- `Electric_Field_Ey_frames.png`: 4 plots of a laser focusing in a vacuum used in place of the GIF for the paper
+
+## Compiling and running EPOCH
+
+1. `git clone --recursive https://github.com/epochpic/epoch.git`
+2. Install libraries
+	1. (ON MAC) `brew install open-mpi`
+	2. (LINUX) `sudo apt install gfortran openmpi-bin openmpi-common libopenmpi-dev libgtk2.0-dev`
+3. Open the `epoch2d` folder
+4. Compile the executable `make COMPILER=gfortran MPIF90=mpif90 -j4`
+5. Run the simulation `mpirun -n 8 ./bin/epoch2d <<< sdf-xarray/joss`
+
+## Building the JOSS PDF
+
+`pandoc paper.md --citeproc --to=pdf -o paper.pdf`

joss/generate_figures.py

@@ -0,0 +1,38 @@
+import matplotlib.pyplot as plt
+
+import sdf_xarray as sdfxr
+
+plt.rcParams.update({"font.size": 13})
+
+# Save a plot of a single SDF
+ds = sdfxr.open_dataset("0010.sdf")
+ds = ds.epoch.rescale_coords(1e6, "µm", ["X_Grid_mid", "Y_Grid_mid"])
+ds["Electric_Field_Ey"].epoch.plot()
+plt.tight_layout()
+plt.savefig("Electric_Field_Ey.png", dpi=500)
+plt.close()
+
+# Generate the animation
+ds = sdfxr.open_mfdataset("*.sdf")
+ds = ds.epoch.rescale_coords(1e15, "fs", "time")
+ds = ds.epoch.rescale_coords(1e6, "µm", ["X_Grid_mid", "Y_Grid_mid"])
+
+anim = ds["Electric_Field_Ey"].epoch.animate()
+plt.tight_layout()
+anim.save("Electric_Field_Ey.gif", fps=10, dpi=500)
+plt.close()
+
+# Generate 4 frames in place of the animation
+plt.rcParams.update({"font.size": 16})
+fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(14, 8))
+
+flux_x = ds["Electric_Field_Ey"]
+# Mimic the normalized colormap that would be built if this was an actual animation
+norm = plt.Normalize(vmin=flux_x.min().values, vmax=flux_x.max().values)
+flux_x.isel(time=5).epoch.plot(ax=ax1, norm=norm)
+flux_x.isel(time=10).epoch.plot(ax=ax2, norm=norm)
+flux_x.isel(time=15).epoch.plot(ax=ax3, norm=norm)
+flux_x.isel(time=20).epoch.plot(ax=ax4, norm=norm)
+
+plt.tight_layout()
+fig.savefig("Electric_Field_Ey_frames.png", dpi=500)

joss/input.deck

@@ -0,0 +1,61 @@
+begin:control
+    nx = 800
+    ny = 400
+    t_end = 200e-15
+    x_min = 0
+    x_max = 50e-6
+    y_min = -10e-6
+    y_max = 10e-6
+    stdout_frequency = 100
+end:control
+
+begin:boundaries
+    bc_x_min = simple_laser
+    bc_x_max = open
+    bc_y_min = open
+    bc_y_max = open
+end:boundaries
+
+begin:constant
+    I_fwhm = 2.0e-6          # FWHM of laser intensity
+    I_peak_Wcm2 = 1.0e18     # 0.5 * eps0 * c * E_peak^2
+    las_lambda = 1.0e-6      # Laser wavelength
+    foc_dist = 25.0e-6       # Boundary to focal point distance
+    lambda_L = 0.8e-6        # Wavelength of the laser
+    tau_fwhm_L = 20e-15      # Laser full width half maximum
+    y_fwhm_L = 2.4e-6        # Laser focal spot originally 2.4 (3x wavelength)
+end:constant
+
+begin:constant
+  w_t = tau_fwhm_L / sqrt(2*loge(2)) # Beam waist in t
+  w_y = y_fwhm_L / sqrt(2*loge(2)) # Beam waist in y
+  t_hw01m = 0.5 * tau_fwhm_L * sqrt(loge(10)/loge(2)) # Half width 0.1 maximum
+
+  x_foc = foc_dist # Boundary to focal point distance
+  k_L = 2.0 * pi / lambda_L # Laser wave number
+  x_Rr = pi * w_y^2 / lambda_L # Rayleigh range
+  omega_L = 2 * pi * c / lambda_L # Angular frequency of the laser
+
+  w_boundary = w_y * sqrt(1 + (x_foc/x_Rr)^2) # Waist on boundary
+  I_boundary = I_peak_Wcm2 * (w_y / w_boundary)^2 # Intens. on boundary
+  r_curve = x_foc * (1 + (x_Rr/x_foc)^2) # Boundary curv. rad.
+  phase_Gouy = atan(-x_foc/r_curve) # Boundary Gouy shift
+end:constant
+
+begin:laser
+  boundary = x_min
+  intensity_w_cm2 = I_boundary
+  omega = omega_L
+  phase = k_L * y^2 / (2 * r_curve) - phase_Gouy
+  profile = gauss(y, 0, w_boundary) # Spatial profile
+  t_profile = gauss(time, t_hw01m, w_t) # Temporal profile
+  t_start = start
+  t_end = end
+end:laser
+
+begin:output
+    name = o1
+    dt_snapshot = 10 * femto
+    ey = always
+    bz = always
+end:output

joss/paper.bib

@@ -0,0 +1,199 @@
+@article{arber:2015,
+  title     = {Contemporary particle-in-cell approach to laser-plasma modelling},
+  volume    = {57},
+  issn      = {1361-6587},
+  url       = {http://dx.doi.org/10.1088/0741-3335/57/11/113001},
+  doi       = {10.1088/0741-3335/57/11/113001},
+  number    = {11},
+  journal   = {Plasma Physics and Controlled Fusion},
+  publisher = {IOP Publishing},
+  author    = {Arber,  T D and Bennett,  K and Brady,  C S and Lawrence-Douglas,  A and Ramsay,  M G and Sircombe,  N J and Gillies,  P and Evans,  R G and Schmitz,  H and Bell,  A R and Ridgers,  C P},
+  year      = {2015},
+  month     = Sept,
+  pages     = {113001}
+}
+@article{hoyer:2017,
+  title     = {xarray: {N-D} labeled arrays and datasets in {Python}},
+  author    = {Hoyer, S. and J. Hamman},
+  journal   = {Journal of Open Research Software},
+  volume    = {5},
+  number    = {1},
+  year      = {2017},
+  publisher = {Ubiquity Press},
+  doi       = {10.5334/jors.148},
+  url       = {https://doi.org/10.5334/jors.148}
+}
+@article{granger:2021,
+  author   = {Granger, Brian E. and Pérez, Fernando},
+  journal  = {Computing in Science & Engineering},
+  title    = {Jupyter: Thinking and Storytelling With Code and Data},
+  year     = {2021},
+  volume   = {23},
+  number   = {2},
+  pages    = {7--14},
+  keywords = {Open source software;Scientific computing;Machine learning;Data science;Open source software;Meteorology},
+  doi      = {10.1109/MCSE.2021.3059263}
+}
+@article{hunter:2007,
+  author    = {Hunter, J. D.},
+  title     = {Matplotlib: A 2D graphics environment},
+  journal   = {Computing in Science \& Engineering},
+  volume    = {9},
+  number    = {3},
+  pages     = {90--95},
+  publisher = {IEEE COMPUTER SOC},
+  doi       = {10.1109/MCSE.2007.55},
+  year      = 2007
+}
+@article{behnel:2010,
+  author   = {Behnel, S. and Bradshaw, R. and Citro, C. and Dalcin, L. and Seljebotn, D.S. and Smith, K.},
+  journal  = {Computing in Science Engineering},
+  title    = {Cython: The Best of Both Worlds},
+  year     = {2011},
+  month    = march-april,
+  volume   = {13},
+  number   = {2},
+  pages    = {31 -39},
+  keywords = {Cython language;Fortran code;Python language extension;numerical loops;programming language;C language;numerical analysis;},
+  doi      = {10.1109/MCSE.2010.118},
+  issn     = {1521-9615}
+}
+@article{harris:2020,
+  title     = {Array programming with {NumPy}},
+  author    = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J.
+               van der Walt and Ralf Gommers and Pauli Virtanen and David
+               Cournapeau and Eric Wieser and Julian Taylor and Sebastian
+               Berg and Nathaniel J. Smith and Robert Kern and Matti Picus
+               and Stephan Hoyer and Marten H. van Kerkwijk and Matthew
+               Brett and Allan Haldane and Jaime Fern{\'{a}}ndez del
+               R{\'{i}}o and Mark Wiebe and Pearu Peterson and Pierre
+               G{\'{e}}rard-Marchant and Kevin Sheppard and Tyler Reddy and
+               Warren Weckesser and Hameer Abbasi and Christoph Gohlke and
+               Travis E. Oliphant},
+  year      = {2020},
+  month     = sep,
+  journal   = {Nature},
+  volume    = {585},
+  number    = {7825},
+  pages     = {357--362},
+  doi       = {10.1038/s41586-020-2649-2},
+  publisher = {Springer Science and Business Media {LLC}},
+  url       = {https://doi.org/10.1038/s41586-020-2649-2}
+}
+@inproceedings{mckinney:2010,
+  author    = { {W}es {M}c{K}inney },
+  title     = { {D}ata {S}tructures for {S}tatistical {C}omputing in {P}ython },
+  booktitle = { {P}roceedings of the 9th {P}ython in {S}cience {C}onference },
+  pages     = { 56 - 61 },
+  year      = { 2010 },
+  editor    = { {S}t\'efan van der {W}alt and {J}arrod {M}illman },
+  doi       = { 10.25080/Majora-92bf1922-00a }
+}
+@misc{rew:1989,
+  doi       = {10.5065/D6H70CW6},
+  url       = {http://www.unidata.ucar.edu/software/netcdf/},
+  author    = {Rew,  Russ and Davis,  Glenn and Emmerson,  Steve and Cormack,  Cathy and Caron,  John and Pincus,  Robert and Hartnett,  Ed and Heimbigner,  Dennis and Appel,  Lynton and Fisher,  Ward},
+  keywords  = {Software,  Free computer software,  Open source software,  Systems software,  Application program interfaces,  Metadata},
+  language  = {en},
+  title     = {Unidata NetCDF},
+  publisher = {NSF Unidata},
+  year      = {1989},
+  copyright = {UCAR/Unidata Open Source Software License}
+}
+@inproceedings{schreiner:2024,
+  author = {Schreiner, III, Henry and Fillion-Robin, Jean-Christophe and McCormick, Matt},
+  doi    = {10.25080/FMKR8387},
+  month  = jul,
+  series = {SciPy 2024},
+  title  = {{Scikit-build-core}},
+  year   = {2024}
+}
+@misc{pypa:2020,
+  author    = {{cibuildwheel Developers}},
+  title     = {{cibuildwheel}},
+  year      = {2020},
+  publisher = {{Python Packaging Authority}},
+  journal   = {GitHub repository},
+  url       = {https://github.com/pypa/cibuildwheel}
+}
+@software{hill:2024a,
+  author = {Hill, Peter and Adams, Joel L.},
+  month  = apr,
+  doi    = {10.5281/zenodo.15586339},
+  title  = {{epydeck: EPOCH input file reader/writer}},
+  url    = {https://github.com/epochpic/epydeck},
+  year   = {2024}
+}
+@software{hill:2024b,
+  author = {Hill, Peter and Adams, Joel L. and Dior, Lawrence},
+  month  = may,
+  doi    = {doi.org/10.5281/zenodo.17106949},
+  title  = {{epyscan: Generate EPOCH campaigns over a parameter space using different sampling methods}},
+  url    = {https://github.com/epochpic/epyscan},
+  year   = {2024}
+}
+@inproceedings{matthew:2015,
+  author    = { Matthew Rocklin },
+  title     = { Dask: Parallel Computation with Blocked algorithms and Task Scheduling },
+  booktitle = { Proceedings of the 14th Python in Science Conference },
+  pages     = { 130 - 136 },
+  year      = { 2015 },
+  editor    = { Kathryn Huff and James Bergstra },
+  url       = {https://www.dask.org}
+}
+@misc{childs:2012,
+  author = {Childs, Hank and Brugger, Eric and Whitlock, Brad and Meredith, Jeremy and Ahern, Sean and Pugmire, David and Biagas, Kathleen and Miller, Mark C. and Harrison, Cyrus and Weber, Gunther H. and Krishnan, Hari and Fogal, Thomas and Sanderson, Allen and Garth, Christoph and Bethel, E. Wes and Camp, David and Rubel, Oliver and Durant, Marc and Favre, Jean M. and Navratil, Paul},
+  doi    = {10.1201/b12985},
+  title  = {{High Performance Visualization--Enabling Extreme-Scale Scientific Insight}},
+  url    = {https://visit.llnl.gov},
+  year   = {2012}
+}
+@software{matlab:2022,
+  year      = {2022},
+  author    = {The MathWorks Inc.},
+  title     = {MATLAB version: 9.13.0 (R2022b)},
+  publisher = {The MathWorks Inc.},
+  address   = {Natick, Massachusetts, United States},
+  url       = {https://www.mathworks.com}
+}
+@misc{huebl:2015,
+  author       = {Huebl, Axel and Lehe, R{\'e}mi and Vay, Jean-Luc and Grote, David P. and Sbalzarini, Ivo and Kuschel, Stephan and Sagan, David and P{\'e}rez, Fr{\'e}d{\'e}ric and Koller, Fabian and Bussmann, Michael},
+  title        = {{openPMD: A meta data standard for particle and mesh based data}},
+  year         = 2015,
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.591699},
+  url          = {https://www.openPMD.org},
+  howpublished = {https://github.com/openPMD}
+}
+@misc{bennett:2014a,
+  author    = {Bennett, keith},
+  title     = {{SDF}},
+  year      = {2014},
+  publisher = {Warwick Plasma Group},
+  journal   = {GitHub repository},
+  url       = {https://github.com/epochpic/SDF}
+}
+@misc{bennett:2014b,
+  author    = {Bennett, keith and Wood, Andrew},
+  title     = {{SDF_C}},
+  year      = {2014},
+  publisher = {Warwick Plasma Group},
+  journal   = {GitHub repository},
+  url       = {https://github.com/epochpic/SDF_C}
+}
+@misc{grecco:2012,
+  author    = {{Pint Developers}},
+  title     = {{Pint}},
+  year      = {2012},
+  publisher = {Hernan Grecco},
+  journal   = {GitHub repository},
+  url       = {https://github.com/hgrecco/pint}
+}
+@misc{magin:2020,
+  author    = {Magin, Justus and Nicholas, Tom and Pflüger, Mika and Thielen, JT and Keys, Simon and Patel, Bhavin and van der Marel, Martijn and Bovy, Benoit},
+  title     = {{pint-xarray}},
+  year      = {2020},
+  publisher = {Xarray Contributions},
+  journal   = {GitHub repository},
+  url       = {https://github.com/xarray-contrib/pint-xarray}
+}