Skip to content

JOSS article #717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
otzi5300 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

JOSS article #717

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 203 additions & 0 deletions docs/joss/example_paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
106 changes: 106 additions & 0 deletions docs/joss/intructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
24 changes: 24 additions & 0 deletions docs/joss/paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading