diff --git a/docs/joss/example_paper.md b/docs/joss/example_paper.md new file mode 100644 index 000000000..9ec547d3d --- /dev/null +++ b/docs/joss/example_paper.md @@ -0,0 +1,203 @@ +--- +title: 'Gala: A Python package for galactic dynamics' +tags: + - Python + - astronomy + - dynamics + - galactic dynamics + - milky way +authors: + - name: Adrian M. Price-Whelan + orcid: 0000-0000-0000-0000 + equal-contrib: true + affiliation: "1, 2" # (Multiple affiliations must be quoted) + - name: Author Without ORCID + equal-contrib: true # (This is how you can denote equal contributions between multiple authors) + affiliation: 2 + - name: Author with no affiliation + corresponding: true # (This is how to denote the corresponding author) + affiliation: 3 + - given-names: Ludwig + dropping-particle: van + surname: Beethoven + affiliation: 3 +affiliations: + - name: Lyman Spitzer, Jr. Fellow, Princeton University, United States + index: 1 + ror: 00hx57361 + - name: Institution Name, Country + index: 2 + - name: Independent Researcher, Country + index: 3 +date: 13 August 2017 +bibliography: paper.bib + +# Optional fields for papers that are part of a joint submission. +# For example, submitting to a AAS journal too, see this blog post: +# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing +# +# If you are not making a joint submission you should remove these lines. +# +aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it. +aas-journal: Astrophysical Journal <- The name of the AAS journal. +--- + +# Summary + +The forces on stars, galaxies, and dark matter under external gravitational +fields lead to the dynamical evolution of structures in the universe. The orbits +of these bodies are therefore key to understanding the formation, history, and +future state of galaxies. The field of "galactic dynamics," which aims to model +the gravitating components of galaxies to study their structure and evolution, +is now well-established, commonly taught, and frequently used in astronomy. +Aside from toy problems and demonstrations, the majority of problems require +efficient numerical tools, many of which require the same base code (e.g., for +performing numerical orbit integration). + +# Statement of need + +`Gala` is an Astropy-affiliated Python package for galactic dynamics. Python +enables wrapping low-level languages (e.g., C) for speed without losing +flexibility or ease-of-use in the user-interface. The API for `Gala` was +designed to provide a class-based and user-friendly interface to fast (C or +Cython-optimized) implementations of common operations such as gravitational +potential and force evaluation, orbit integration, dynamical transformations, +and chaos indicators for nonlinear dynamics. `Gala` also relies heavily on and +interfaces well with the implementations of physical units and astronomical +coordinate systems in the `Astropy` package [@astropy] (`astropy.units` and +`astropy.coordinates`). + +`Gala` was designed to be used by both astronomical researchers and by +students in courses on gravitational dynamics or astronomy. It has already been +used in a number of scientific publications [@Pearson:2017] and has also been +used in graduate courses on Galactic dynamics to, e.g., provide interactive +visualizations of textbook material [@Binney:2008]. The combination of speed, +design, and support for Astropy functionality in `Gala` will enable exciting +scientific explorations of forthcoming data releases from the *Gaia* mission +[@gaia] by students and experts alike. + +# State of the field + +Several tools exist for galactic dynamics computations: +`galpy` [@Bovy:2015] is a Python package with similar goals, +providing orbit integration and potential classes for galactic dynamics. +`NEMO` [@Teuben:1995] is a well-established, comprehensive stellar dynamics +toolbox written primarily in C, offering extensive functionality but with a +steeper learning curve and less integration with modern Python workflows. +Other tools like `GalPot` provide specific Milky Way potential models but lack +the broader dynamical analysis capabilities. + +`Gala` was built rather than contributing to existing projects for several +reasons. First, `Gala` was designed from the ground up to integrate seamlessly +with the Astropy ecosystem, using `astropy.units` and `astropy.coordinates` +as core dependencies rather than optional features. This tight integration +enables natural workflows for astronomers already using Astropy. Second, +`Gala`'s object-oriented API with consistent interfaces across subpackages +(potentials, integrators, dynamics) provides a more modular and extensible +design than alternatives available at the time. Third, `Gala` fills a specific +niche between simple demonstration codes and full N-body simulation packages +like `Gadget` [@Springel:2005] – it focuses on the common tasks in galactic +dynamics research (orbit integration, potential evaluation, coordinate +transformations) while maintaining both performance through C implementations +and usability through its Python interface. + +# Software design + +`Gala`'s design philosophy is based on three core principles: (1) to provide a +user-friendly, modular, object-oriented API, (2) to use community tools and +standards (e.g., Astropy for coordinates and units handling), and (3) to use +low-level code (C/C++/Cython) for performance while keeping the user interface +in Python. Within each of the main subpackages in `gala` (`gala.potential`, +`gala.dynamics`, `gala.integrate`, etc.), we try to maintain a consistent API +for classes and functions. For example, all potential classes share a common +base class and implement methods for computing the potential, forces, density, +and other derived quantities at given positions. This also works for +compositions of potentials (i.e., multi-component potential models), which +share the potential base class but also act as a dictionary-like container for +different potential components. As another example, all integrators implement a +common interface for numerically integrating orbits. The integrators and core +potential functions are all implemented in C without support for units, but the +Python layer handles unit conversions and prepares data to dispatch to the C +layer appropriately.Within the coordinates subpackage, we extend Astropy's +coordinate classes to add more specialized coordinate frames and +transformations that are relevant for Galactic dynamics and Milky Way research. + +# Research impact statement + +`Gala` has demonstrated significant research impact and grown both its user base +and contributor community since its initial release. The package has evolved +through contributions from over 18 developers beyond the original core developer +(@adrn), with community members adding new features, reporting bugs, and +suggesting new features. + +While `Gala` started as a tool primarily to support the core developer's +research, it has expanded organically to support a range of applications across +domains in astrophysics related to Milky Way and galactic dynamics. The package +has been used in over 400 publications (according to Google Scholar) spanning +topics in galactic dynamics such as modeling stellar streams [@Pearson:2017], +Milky Way mass modeling, and interpreting kinematic and stellar population +trends in the Galaxy. `Gala` is integrated within the Astropy ecosystem as an +affiliated package and has built functionality that extends the widely-used +`astropy.units` and `astropy.coordinates` subpackages. `Gala`'s impact extends +beyond citations in research: Because of its focus on usability and user +interface design, `Gala` has also been incorporated into graduate-level galactic +dynamics curricula at multiple institutions. + +`Gala` has been downloaded over 100,000 times from PyPI and conda-forge yearly +(or ~2,000 downloads per week) over the past few years, demonstrating a broad +and active user community. Users span career stages from graduate students to +faculty and other established researchers and represent institutions around the +world. This broad adoption and active participation validate `Gala`'s role as +core community infrastructure for galactic dynamics research. + +# Mathematics + +Single dollars ($) are required for inline mathematics e.g. $f(x) = e^{\pi/x}$ + +Double dollars make self-standing equations: + +$$\Theta(x) = \left\{\begin{array}{l} +0\textrm{ if } x < 0\cr +1\textrm{ else} +\end{array}\right.$$ + +You can also use plain \LaTeX for equations +\begin{equation}\label{eq:fourier} +\hat f(\omega) = \int_{-\infty}^{\infty} f(x) e^{i\omega x} dx +\end{equation} +and refer to \autoref{eq:fourier} from text. + +# Citations + +Citations to entries in paper.bib should be in +[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) +format. + +If you want to cite a software repository URL (e.g. something on GitHub without a preferred +citation) then you can do it with the example BibTeX entry below for @fidgit. + +For a quick reference, the following citation commands can be used: +- `@author:2001` -> "Author et al. (2001)" +- `[@author:2001]` -> "(Author et al., 2001)" +- `[@author1:2001; @author2:2001]` -> "(Author1 et al., 2001; Author2 et al., 2002)" + +# Figures + +Figures can be included like this: +![Caption for example figure.\label{fig:example}](figure.png) +and referenced from text using \autoref{fig:example}. + +Figure sizes can be customized by adding an optional second parameter: +![Caption for example figure.](figure.png){ width=20% } + +# AI usage disclosure + +No generative AI tools were used in the development of this software, the writing +of this manuscript, or the preparation of supporting materials. + +# Acknowledgements + +We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong +Oh, and support from Kathryn Johnston during the genesis of this project. + +# References \ No newline at end of file diff --git a/docs/joss/intructions.md b/docs/joss/intructions.md new file mode 100644 index 000000000..34092d494 --- /dev/null +++ b/docs/joss/intructions.md @@ -0,0 +1,106 @@ +# JOSS (Journal of Open Source Software) + +**Links** +- [JOSS Submission Guide](https://joss.readthedocs.io/en/latest/submitting.html) +- [JOSS Review Criteria](https://joss.readthedocs.io/en/latest/review_criteria.html) +- [Example Paper](https://joss.readthedocs.io/en/aper.html + +## Key Requirements + +### Open Source +- Must use an **OSI-approved open source license**. +- Must have a **public development history**. +- Source code must be hosted where users can: + - Browse the code + - Open issues + - Submit code changes without manual account approval or payment + +### Research Relevance +- Must have an **obvious research application**. +- Should demonstrate research impact through: + - Publications + - Use in scientific analysis + - External adopters + - Integrations into research workflows + +### Authorship +- You must be a **major contributor** to the software. +- You must have a GitHub account to participate in the review process. + +### Paper Requirements +- The paper should **describe the software**, not new research results obtained with it. +- Paper files (`paper.md`, bibliography, figures) must be hosted in the same Git repository as the software. +- The paper may live in a temporary branch, but that branch should be created from the default branch so the software source code is included. + +--- + +## Before Submitting + +### 1. Publish the Software +- Host the software in a public repository (GitHub, Bitbucket, GitLab, etc.). +- Add an **OSI-approved license**: + - https://opensource.org/licenses + +### 2. Meet Review Criteria +The software should be: +- Functional and reasonably complete +- Well documented +- Tested +- Reproducible where applicable +- Easy for others to install and use + +### 3. Write the Paper +Create a `paper.md` file containing: +- Title +- Authors +- Affiliations +- Summary of the software +- Statement of need +- Key references + +Reference: +- https://joss.readthedocs.io/en/latest/example_paper.html + +### 4. (Optional) Create Metadata +JOSS provides a metadata-generation script: +- https://gist.github.com/arfon/478b2ed49e11f984d6fb + +--- + +## JOSS Scope Checklist + +- [ ] Open source according to the OSI definition +- [ ] Public repository +- [ ] Public issue tracker +- [ ] Public contribution workflow +- [ ] Clear research application +- [ ] Sufficient documentation +- [ ] Automated tests or validation procedures +- [ ] Evidence of research impact or adoption +- [ ] Authors are major contributors +- [ ] Software paper written in `paper.md` + +--- + +## Submission Process + +Submission is simple: + +1. Fill in the submission form: + - http://joss.theoj.org/papers/new + +2. Wait for a managing editor to create a pre-review issue in: + - https://github.com/openjournals/joss-reviews + +3. Participate in the open review process on GitHub. + +--- + +## Costs + +✅ There are **no submission fees**. + +✅ There are **no publication fees**. + +More information: +- http://joss.theoj.org/about#costs diff --git a/docs/joss/paper.md b/docs/joss/paper.md new file mode 100644 index 000000000..bdb2ee087 --- /dev/null +++ b/docs/joss/paper.md @@ -0,0 +1,24 @@ +--- +title: 'Modelskill: ...' +tags: + - Python + - oceanography + - validation +authors: + - name: Henrik Andersson + equal-contrib: true + affiliation: 1 + - name: Lars Jonasson + equal-contrib: true # (This is how you can denote equal contributions between multiple authors) + affiliation: 2 +affiliations: + - name: DHI, Denmark + index: 1 + - name: DHI, Sweden + index: 2 + +date: 1 October 2026 +bibliography: paper.bib +--- + +# Summary \ No newline at end of file