Add JOSS paper citation and code

.github/workflows/draft-pdf.yml

@@ -0,0 +1,31 @@
+name: JossPaperCompilation
+
+on:
+  push:
+    paths:
+      - papers/joss/**
+  pull_request:
+    paths:
+    - 'papers/joss/**'
+  workflow_dispatch:
+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: papers/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: papers/joss/paper.pdf

.gitignore

@@ -323,3 +323,6 @@ results/
 
 # Pycharm
 *.idea/
+
+# JOSS
+jats/

CITATION.cff

@@ -1,35 +1,62 @@
-cff-version: 1.2.0
-title: 'PyBOP: A Python package for battery model optimisation and parameterisation'
-message: >-
-  If you use this software, please cite the article below.
+cff-version: "1.2.0"
 authors:
-  - given-names: Brady
-    family-names: Planden
+- family-names: Planden
+  given-names: Brady
+  orcid: "https://orcid.org/0000-0002-1082-9125"
+- family-names: Courtier
+  given-names: Nicola E.
+  orcid: "https://orcid.org/0000-0002-5714-1096"
+- family-names: Robinson
+  given-names: Martin
+  orcid: "https://orcid.org/0000-0002-1572-6782"
+- family-names: Khetarpal
+  given-names: Agriya
+  orcid: "https://orcid.org/0000-0002-1112-1786"
+- family-names: Planella
+  given-names: Ferran Brosa
+  orcid: "https://orcid.org/0000-0001-6363-2812"
+- family-names: Howey
+  given-names: David A.
+  orcid: "https://orcid.org/0000-0002-0620-3955"
+contact:
+- family-names: Howey
+  given-names: David A.
+  orcid: "https://orcid.org/0000-0002-0620-3955"
+doi: 10.5281/zenodo.17711656
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Planden
+    given-names: Brady
     orcid: "https://orcid.org/0000-0002-1082-9125"
-  - given-names: Nicola E.
-    family-names: Courtier
+  - family-names: Courtier
+    given-names: Nicola E.
     orcid: "https://orcid.org/0000-0002-5714-1096"
-  - given-names: Martin
-    family-names: Robinson
+  - family-names: Robinson
+    given-names: Martin
     orcid: "https://orcid.org/0000-0002-1572-6782"
-  - given-names: Agriya
-    family-names: Khetarpal
+  - family-names: Khetarpal
+    given-names: Agriya
     orcid: "https://orcid.org/0000-0002-1112-1786"
-  - given-names: Ferran
-    family-names: Brosa Planella
+  - family-names: Planella
+    given-names: Ferran Brosa
     orcid: "https://orcid.org/0000-0001-6363-2812"
-  - given-names: David A.
-    family-names: Howey
+  - family-names: Howey
+    given-names: David A.
     orcid: "https://orcid.org/0000-0002-0620-3955"
-
-keywords:
-  - "python"
-  - "battery models"
-  - "parameter inference"
-  - "optimization"
-
-journal: "arXiv"
-date-released: 2024-12-20
-doi: 10.48550/arXiv.2412.15859
-version: "25.11" # Update this alongside new releases
-repository-code: 'https://www.github.com/pybop-team/pybop'
+  date-published: 2025-12-03
+  doi: 10.21105/joss.07874
+  issn: 2475-9066
+  issue: 116
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 7874
+  title: "PyBOP: A Python package for battery model optimisation and
+    parameterisation"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.07874"
+  volume: 10
+title: "PyBOP: A Python package for battery model optimisation and
+  parameterisation"

README.md

@@ -14,6 +14,7 @@
   [![nbviewer](https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg)](https://nbviewer.org/github/pybop-team/PyBOP/tree/develop/examples/notebooks/)
   [![Static Badge](https://img.shields.io/badge/https%3A%2F%2Fpybop-team.github.io%2Fpybop-bench%2F?label=Benchmarks)](https://pybop-team.github.io/pybop-bench/)
   [![Releases](https://img.shields.io/github/v/release/pybop-team/PyBOP?color=gold)](https://github.com/pybop-team/PyBOP/releases)
+  [![DOI](https://joss.theoj.org/papers/10.21105/joss.07874/status.svg)](https://doi.org/10.21105/joss.07874)
 
 [<ins>Main Branch Examples</ins>](https://github.com/pybop-team/PyBOP/tree/main/examples) [<ins>Develop Branch Examples</ins>](https://github.com/pybop-team/PyBOP/tree/develop/examples)
 

papers/joss/design_plots.py

@@ -0,0 +1,164 @@
+# A script to generate design optimisation plots for the JOSS paper.
+
+
+import numpy as np
+import pybamm
+from pybamm import Parameter
+
+import pybop
+from pybop.plot import PlotlyManager
+
+go = PlotlyManager().go
+np.random.seed(8)
+axis_font_size = 24
+tick_font_size = 20
+
+# Choose which plots to show and save
+create_plot = {}
+create_plot["gravimetric"] = True  # takes longer
+create_plot["prediction"] = True
+
+# Define model and parameter values
+model = pybamm.lithium_ion.SPMe()
+pybop.pybamm.add_variable_to_model(model, "Gravimetric energy density [W.h.kg-1]")
+parameter_values = pybamm.ParameterValues("Chen2020")
+pybop.pybamm.set_formation_concentrations(parameter_values)
+parameter_values.update(
+    {
+        "Electrolyte density [kg.m-3]": Parameter("Separator density [kg.m-3]"),
+        "Negative electrode active material density [kg.m-3]": Parameter(
+            "Negative electrode density [kg.m-3]"
+        ),
+        "Negative electrode carbon-binder density [kg.m-3]": Parameter(
+            "Negative electrode density [kg.m-3]"
+        ),
+        "Positive electrode active material density [kg.m-3]": Parameter(
+            "Positive electrode density [kg.m-3]"
+        ),
+        "Positive electrode carbon-binder density [kg.m-3]": Parameter(
+            "Positive electrode density [kg.m-3]"
+        ),
+        "Positive electrode porosity": 1.0
+        - Parameter("Positive electrode active material volume fraction"),
+        "Cell mass [kg]": pybop.pybamm.cell_mass(),
+    },
+    check_already_exists=False,
+)
+
+# Fitting parameters
+parameter_values.update(
+    {
+        "Positive electrode thickness [m]": pybop.Parameter(
+            initial_value=8.88e-05,
+            prior=pybop.Gaussian(7.56e-05, 3e-05),
+            bounds=[50e-06, 120e-06],
+            transformation=pybop.UnitHyperCube(lower=50e-6, upper=120e-6),
+        ),
+        "Positive electrode active material volume fraction": pybop.Parameter(
+            initial_value=0.42,
+            prior=pybop.Gaussian(0.58, 0.1),
+            bounds=[0.3, 0.825],
+            transformation=pybop.UnitHyperCube(lower=0.3, upper=0.825),
+        ),
+    }
+)
+
+# Define test protocol
+experiment = pybamm.Experiment(["Discharge at 1C until 2.5 V (10 second period)"])
+Q = parameter_values["Nominal cell capacity [A.h]"]
+print(f"The 1C rate is {Q} A.")
+
+# Generate problem
+simulator = pybop.pybamm.Simulator(
+    model,
+    parameter_values=parameter_values,
+    protocol=experiment,
+    solver=pybamm.IDAKLUSolver(atol=1e-6, rtol=1e-6),
+)
+cost = pybop.DesignCost(target="Gravimetric energy density [W.h.kg-1]")
+problem = pybop.Problem(simulator, cost)
+
+# Set up the optimiser
+options = pybop.PintsOptions(max_iterations=250, max_unchanged_iterations=45)
+optim = pybop.NelderMead(problem, options=options)
+
+# Run optimisation
+result = optim.run()
+print(result)
+print("Estimated parameters:", result.x)
+print(f"Initial gravimetric energy density: {problem(result.x0):.1f} W.h.kg-1")
+print(f"Optimised gravimetric energy density: {problem(result.x):.1f} W.h.kg-1")
+
+if create_plot["gravimetric"]:
+    # Plot the cost landscape with optimisation path
+    gravimetric_fig = pybop.plot.contour(
+        result,
+        steps=25,
+        show=False,
+        xaxis=dict(
+            title=dict(
+                text="Positive electrode thickness / m", font_size=axis_font_size
+            ),
+            tickfont_size=tick_font_size,
+            exponentformat="power",
+        ),
+        yaxis=dict(title_font_size=axis_font_size, tickfont_size=tick_font_size),
+        legend=dict(
+            orientation="h",
+            yanchor="bottom",
+            y=1.02,
+            xanchor="right",
+            x=1,
+            font_size=tick_font_size,
+        ),
+        coloraxis_colorbar=dict(tickfont_size=tick_font_size),
+        margin=dict(t=50),
+        title=None,
+    )
+    gravimetric_fig.write_image("figures/individual/design_gravimetric.pdf")
+
+if create_plot["prediction"]:
+    # Plot the timeseries output
+    problem.target = "Voltage [V]"
+    figs = pybop.plot.problem(
+        problem,
+        inputs=result.best_inputs,
+        title=None,
+        legend=dict(
+            orientation="h",
+            yanchor="bottom",
+            y=1.02,
+            xanchor="right",
+            x=1,
+            font_size=tick_font_size - 2,
+        ),
+        xaxis=dict(
+            showline=True,
+            linewidth=1,
+            linecolor="black",
+            mirror=True,
+            title_font_size=axis_font_size,
+            tickfont_size=tick_font_size,
+        ),
+        yaxis=dict(
+            showline=True,
+            linewidth=1,
+            linecolor="black",
+            mirror=True,
+            title_font_size=axis_font_size,
+            tickfont_size=tick_font_size,
+        ),
+        margin=dict(t=60, b=84, r=50, l=15),
+        show=False,
+    )
+
+    prediction_fig = figs[0]
+    prediction_fig.data[1].update(line=dict(color="#00CC97"))
+    prediction_fig.data[
+        0
+    ].name = f"Initial: {problem(result.x0):.1f} W&#8239;h&#8239;kg<sup>-1</sup>"
+    prediction_fig.data[
+        1
+    ].name = f"Optimised: {problem(result.x):.1f} W&#8239;h&#8239;kg<sup>-1</sup>"
+    prediction_fig.show()
+    prediction_fig.write_image("figures/individual/design_prediction.pdf")

papers/joss/image_combine.sh

@@ -0,0 +1,9 @@
+pdfjam --nup 2x1 figures/individual/design_prediction.pdf figures/individual/design_gravimetric.pdf --landscape --outfile figures/combined/design.pdf --papersize '{420px,900px}'
+
+pdfjam --nup 3x1 figures/individual/gradient_parameters.pdf figures/individual/evolution_parameters.pdf figures/individual/heuristic_parameters.pdf --landscape --outfile figures/combined/optimisers_parameters.pdf --papersize '{900px,1440px}'
+
+pdfjam --nup 2x1 figures/individual/convergence_minimising.pdf figures/individual/convergence_maximising.pdf --landscape --outfile figures/combined/converge.pdf --papersize '{400px,900px}' --trim '0cm 0cm 0cm 1.5cm' --clip true
+
+pdfjam --nup 2x1 figures/individual/simulation.pdf figures/individual/landscape.pdf --landscape --outfile figures/combined/sim-landscape.pdf --papersize '{420px,900px}'
+
+pdfjam --nup 2x1 figures/individual/impedance_spectrum.pdf figures/individual/impedance_contour.pdf --landscape --outfile figures/combined/impedance.pdf --papersize '{420px,900px}'