From cb681d9c45862565c1c881c4435ff66b7f9a9db5 Mon Sep 17 00:00:00 2001 From: Keichi Takahashi Date: Tue, 21 Sep 2021 12:20:09 +0900 Subject: [PATCH 1/4] Add JOSS paper template --- paper/paper.bib | 59 +++++++++++++++++++++++++ paper/paper.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 paper/paper.bib create mode 100644 paper/paper.md diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..4e4544a4 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,59 @@ +@article{Pearson:2017, + url = {http://adsabs.harvard.edu/abs/2017arXiv170304627P}, + Archiveprefix = {arXiv}, + Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.}, + Eprint = {1703.04627}, + Journal = {ArXiv e-prints}, + Keywords = {Astrophysics - Astrophysics of Galaxies}, + Month = mar, + Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}}, + Year = 2017 +} + +@book{Binney:2008, + url = {http://adsabs.harvard.edu/abs/2008gady.book.....B}, + Author = {{Binney}, J. and {Tremaine}, S.}, + Booktitle = {Galactic Dynamics: Second Edition, by James Binney and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by Princeton University Press, Princeton, NJ USA, 2008.}, + Publisher = {Princeton University Press}, + Title = {{Galactic Dynamics: Second Edition}}, + Year = 2008 +} + +@article{gaia, + author = {{Gaia Collaboration}}, + title = "{The Gaia mission}", + journal = {Astronomy and Astrophysics}, + archivePrefix = "arXiv", + eprint = {1609.04153}, + primaryClass = "astro-ph.IM", + keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes}, + year = 2016, + month = nov, + volume = 595, + doi = {10.1051/0004-6361/201629272}, + url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G}, +} + +@article{astropy, + author = {{Astropy Collaboration}}, + title = "{Astropy: A community Python package for astronomy}", + journal = {Astronomy and Astrophysics}, + archivePrefix = "arXiv", + eprint = {1307.6212}, + primaryClass = "astro-ph.IM", + keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools}, + year = 2013, + month = oct, + volume = 558, + doi = {10.1051/0004-6361/201322068}, + url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A} +} + +@misc{fidgit, + author = {A. M. Smith and K. Thaney and M. Hahnel}, + title = {Fidgit: An ungodly union of GitHub and Figshare}, + year = {2020}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/arfon/fidgit} +} diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..10d68a27 --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,112 @@ +--- +title: 'Gala: A Python package for galactic dynamics' +tags: + - Python + - astronomy + - dynamics + - galactic dynamics + - milky way +authors: + - name: Adrian M. Price-Whelan^[co-first author] # note this makes a footnote saying 'co-first author' + orcid: 0000-0003-0872-7098 + affiliation: "1, 2" # (Multiple affiliations must be quoted) + - name: Author Without ORCID^[co-first author] # note this makes a footnote saying 'co-first author' + affiliation: 2 + - name: Author with no affiliation^[corresponding author] + affiliation: 3 +affiliations: + - name: Lyman Spitzer, Jr. Fellow, Princeton University + index: 1 + - name: Institution Name + index: 2 + - name: Independent Researcher + index: 3 +date: 13 August 2017 +bibliography: paper.bib + +# Optional fields if submitting to a AAS journal too, see this blog post: +# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing +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. + +# 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% } + +# Acknowledgements + +We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong +Oh, and support from Kathryn Johnston during the genesis of this project. + +# References From d44fcb63963bd5083694cf0f64a6a84c48576254 Mon Sep 17 00:00:00 2001 From: Keichi Takahashi Date: Tue, 21 Sep 2021 12:33:26 +0900 Subject: [PATCH 2/4] Edit title and author --- paper/paper.md | 32 +++++++------------------------- 1 file changed, 7 insertions(+), 25 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index 10d68a27..60b46a59 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -1,33 +1,15 @@ --- -title: 'Gala: A Python package for galactic dynamics' +title: 'Binary-parser: A blazing-fast declarative parser builder for binary data' tags: - - Python - - astronomy - - dynamics - - galactic dynamics - - milky way + - JavaScript authors: - - name: Adrian M. Price-Whelan^[co-first author] # note this makes a footnote saying 'co-first author' - orcid: 0000-0003-0872-7098 - affiliation: "1, 2" # (Multiple affiliations must be quoted) - - name: Author Without ORCID^[co-first author] # note this makes a footnote saying 'co-first author' - affiliation: 2 - - name: Author with no affiliation^[corresponding author] - affiliation: 3 + - name: Keichi Takahashi + orcid: 0000-0002-1607-5694 + affiliation: 1 affiliations: - - name: Lyman Spitzer, Jr. Fellow, Princeton University - index: 1 - - name: Institution Name - index: 2 - - name: Independent Researcher - index: 3 -date: 13 August 2017 + - name: Nara Institute of Science and Technology +date: 21 September 2021 bibliography: paper.bib - -# Optional fields if submitting to a AAS journal too, see this blog post: -# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing -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 From 3d7bb1092486483757fc54a6354a0507a6442e08 Mon Sep 17 00:00:00 2001 From: Keichi Takahashi Date: Wed, 29 Sep 2021 12:28:05 +0900 Subject: [PATCH 3/4] Drafting paper --- paper/benchmark.pdf | Bin 0 -> 11552 bytes paper/paper.bib | 151 +++++++++++++++++++++++++++--------------- paper/paper.md | 158 +++++++++++++++++++++++--------------------- 3 files changed, 179 insertions(+), 130 deletions(-) create mode 100644 paper/benchmark.pdf diff --git a/paper/benchmark.pdf b/paper/benchmark.pdf new file mode 100644 index 0000000000000000000000000000000000000000..dbc4dde65af33a61f38a08f27489b609858f2315 GIT binary patch literal 11552 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 literal 0 HcmV?d00001 diff --git a/paper/paper.bib b/paper/paper.bib index 4e4544a4..02da5499 100644 --- a/paper/paper.bib +++ b/paper/paper.bib @@ -1,59 +1,100 @@ -@article{Pearson:2017, - url = {http://adsabs.harvard.edu/abs/2017arXiv170304627P}, - Archiveprefix = {arXiv}, - Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.}, - Eprint = {1703.04627}, - Journal = {ArXiv e-prints}, - Keywords = {Astrophysics - Astrophysics of Galaxies}, - Month = mar, - Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}}, - Year = 2017 -} - -@book{Binney:2008, - url = {http://adsabs.harvard.edu/abs/2008gady.book.....B}, - Author = {{Binney}, J. and {Tremaine}, S.}, - Booktitle = {Galactic Dynamics: Second Edition, by James Binney and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by Princeton University Press, Princeton, NJ USA, 2008.}, - Publisher = {Princeton University Press}, - Title = {{Galactic Dynamics: Second Edition}}, - Year = 2008 -} - -@article{gaia, - author = {{Gaia Collaboration}}, - title = "{The Gaia mission}", - journal = {Astronomy and Astrophysics}, - archivePrefix = "arXiv", - eprint = {1609.04153}, - primaryClass = "astro-ph.IM", - keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes}, - year = 2016, - month = nov, - volume = 595, - doi = {10.1051/0004-6361/201629272}, - url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G}, -} - -@article{astropy, - author = {{Astropy Collaboration}}, - title = "{Astropy: A community Python package for astronomy}", - journal = {Astronomy and Astrophysics}, - archivePrefix = "arXiv", - eprint = {1307.6212}, - primaryClass = "astro-ph.IM", - keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools}, - year = 2013, - month = oct, - volume = 558, - doi = {10.1051/0004-6361/201322068}, - url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A} -} - -@misc{fidgit, - author = {A. M. Smith and K. Thaney and M. Hahnel}, - title = {Fidgit: An ungodly union of GitHub and Figshare}, +@misc{djiparsetxt, + author = {Christian Velez}, + title = {Decrypts and parse DJI logs in node}, + publisher = {GitHub}, + journal = {GitHub repository}, year = {2020}, + url = {https://github.com/chrisvm/node-djiparsetxt} +} + +@misc{libsbp, + author = {{Swift Navigation}}, + title = {Swift Binary Protocol client libraries}, publisher = {GitHub}, journal = {GitHub repository}, - url = {https://github.com/arfon/fidgit} + year = {2021}, + url = {https://github.com/swift-nav/libsbp} +} + +@misc{nimrod, + author = {Starbeamrainbowlabs}, + title = {Data downloader for the 1km NIMROD rainfall radar data}, + publisher = {GitHub}, + journal = {GitHub repository}, + year = {2021}, + url = {https://github.com/sbrl/nimrod-data-downloader} +} + +@misc{flexradio, + author = {Stephen Houser}, + title = {NodeRed nodes for working with FlexRadio 6xxx series software defined radios}, + publisher = {GitHub}, + journal = {GitHub repository}, + year = {2021}, + url = {https://github.com/stephenhouser/node-red-contrib-flexradio} +} + +@misc{linky, + author = {Zehir}, + publisher = {GitHub}, + journal = {GitHub repository}, + year = {2021}, + url = {https://github.com/Zehir/eesmart-d2l} +} + +@misc{maxcul, + author = {Florian Beek}, + title = {A pimatic Plugin to control MAX! Heating devices over a Busware CUL stick}, + publisher = {GitHub}, + journal = {GitHub repository}, + year = {2020}, + url = {https://github.com/fbeek/pimatic-maxcul} +} + +@misc{kaitai, + author = {{Kaitai team}}, + title = {Kaitai Struct: declarative language to generate binary data parsers}, + publisher = {GitHub}, + journal = {GitHub repository}, + year = {2021}, + url = {https://github.com/kaitai-io/kaitai_struct} +} + +@inproceedings{nail, + author={Bangert, Julian and Zeldovich, Nickolai}, + booktitle={2014 IEEE Security and Privacy Workshops}, + title={Nail: A Practical Interface Generator for Data Formats}, + year={2014}, + pages={158-166}, + doi={10.1109/SPW.2014.31} +} + +@inproceedings{nom, + author={Couprie, Geoffroy}, + booktitle={2015 IEEE Security and Privacy Workshops}, + title={Nom, A Byte oriented, streaming, Zero copy, Parser Combinators Library in Rust}, + year={2015}, + pages={142-148}, + doi={10.1109/SPW.2015.31} +} + +@inproceedings{parsifal, + author={Levillain, Olivier}, + booktitle={2014 IEEE Security and Privacy Workshops}, + title={Parsifal: A Pragmatic Solution to the Binary Parsing Problems}, + year={2014}, + pages={191-197}, + doi={10.1109/SPW.2014.35} +} + +@article{monadic, + title={Monadic parsing in Haskell}, + volume={8}, + doi={10.1017/S0956796898003050}, + number={4}, + journal={Journal of Functional Programming}, + publisher={Cambridge University Press}, + author={Hutton, Graham and Meijer, Erik}, + year={1998}, + pages={437–444} } diff --git a/paper/paper.md b/paper/paper.md index 60b46a59..13aeabfe 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -1,94 +1,102 @@ --- -title: 'Binary-parser: A blazing-fast declarative parser builder for binary data' +title: 'Binary-parser: A declarative and efficient parser generator for binary data' tags: - JavaScript + - TypeScript + - binary + - parser authors: - name: Keichi Takahashi orcid: 0000-0002-1607-5694 affiliation: 1 affiliations: - name: Nara Institute of Science and Technology -date: 21 September 2021 + index: 1 +date: 27 September 2021 bibliography: paper.bib --- # 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). +This paper presents `binary-parser`, a JavaScript/TypeScript library that +allows users to write high-performance binary parsers, and facilitates the +rapid prototyping of research software that works with binary files and +network protocols. `Binary-parser`'s declarative API is designed such that +expressing complex binary structures is straightforward and easy. In addition +to the high productivity, `binary-parser` utilizes meta-programming to +dynamically generate parser codes to achieve parsing performance equivalent +to a hand-written parser. `Binary-parser` is being used by over 700 GitHub +repositories and 120 npm packages as of September 2021. # 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. - -# 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% } - -# Acknowledgements - -We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong -Oh, and support from Kathryn Johnston during the genesis of this project. +Parsing binary data is a ubiquitous task in developing research software. Many +scientific instruments and software tools use proprietary file formats and +network protocols, while open-source libraries to work with them are often +unavailable or limited. In such situations, the programmer has no choice but +to write a binary parser. However, writing a binary parser by hand is +error-prone and tedious because the programmer faces challenges such as +understanding the specification of the binary format, correctly managing the +byte/bit offsets during parsing, and constructing complex data structures as +outputs. + +`Binary-parser` significantly reduces the programmer's effort by automatically +generating efficient parser code from a declarative description of the binary +format supplied by the user. The generated parser code is converted to a +JavaScript function and executed for efficient parsing. To accommodate diverse +needs by different users, `binary-parser` exposes various options to ensure +flexibility and provide opportunities for customization. + +A large number of software packages have been developed using `binary-parser` +that demonstrates its usefulness and practicality. Some examples include +libraries and applications to work with rainfall radars [@nimrod], +software-defined radio [@flexradio], GNSS receivers [@libsbp], smart meters +[@linky], drones [@djiparsetxt], and thermostats [@maxcul]. + +# Design + +`Binary-parser`'s design is characterized by the following three key features: + +1. **Fast**: `Binary-parser` takes advantage of meta-programming to generate + a JavaScript source code during runtime from the user's description of the + target binary format. The generated source code is then passed to the + `Function` constructor to dynamically create a function that performs + parsing. This design enables `binary-parser` to achieve parsing + performance comparable to a hand-written parser. +2. **Declarative**: As opposed to parser combinator libraries [@monadic; @nom], + `binary-parser` allows the user to express the target binary format in a + declarative manner, similar to a human-readable network protocol or file + format specification. The user can combine _primitive_ parsers (integers, + floating point numbers, bit fields, strings and bytes) using _composite_ + parsers (arrays, choices, nests and pointers) to express a wide variety of + binary formats. +3. **Flexible**: Unlike binary parser generators that use an external Domain + Specific Language (DSL) [@kaitai; @nail], `binary-parser` uses an internal + DSL implemented on top of JavaScript. This design allows the user to + specify most parsing options as return values of user-defined JavaScript + functions that are invoked at runtime. For example, the offset and length + of a field can be computed from another field that has been parsed already. + +# Performance evaluation + +To evaluate the parsing performance of `binary-parser`, we implemented a small +parser using `binary-parser` (v2.0.1) and three major JavaScript binary parser +libraries: `binparse` (v1.2.1), `structron` (v0.4.3) and `destruct.js` (v0.2.9). +We also implemented the same parser using Node.js's Buffer API as a baseline. +The binary data to be parsed was an array of 1,000 coordinates (each expressed +as three 16-bit integers) preceded by the number of coordinates (a 32-bit +integer). The benchmarks were executed on a MacBook Air (Apple M1 CPU, 2020). +The JavaScript runtime was Node.js (v16.9.1). + +![Performance comparison of binary-parser, binparse, structron, destruct.js and a hand-written parser.\label{fig:benchmark}](benchmark.pdf){ width=80% } + +\autoref{fig:benchmark} shows the measurement results. Evidently, +`binary-parser` significantly outperforms its alternatives by a factor of +7.5$\times$ to 180$\times$. The plot also reveals that `binary-parser` +achieves performance equal to a hand-written parser. + +# Acknowledgments + +This work was partly supported by JSPS KAKENHI Grant Number JP20K19808. # References From 6607ea35cb7aefc46c37fa24d3a1cf16fde5491b Mon Sep 17 00:00:00 2001 From: Keichi Takahashi Date: Tue, 12 Oct 2021 18:06:03 +0900 Subject: [PATCH 4/4] Add JOSS badge in README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 180c100e..cb218280 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![build](https://github.com/keichi/binary-parser/workflows/build/badge.svg)](https://github.com/keichi/binary-parser/actions?query=workflow%3Abuild) [![npm](https://img.shields.io/npm/v/binary-parser)](https://www.npmjs.com/package/binary-parser) +[![status](https://joss.theoj.org/papers/ec35c0e3ccc750a5cdab9771e5a6bf21/status.svg)](https://joss.theoj.org/papers/ec35c0e3ccc750a5cdab9771e5a6bf21) Binary-parser is a parser builder for JavaScript that enables you to write efficient binary parsers in a simple and declarative manner.