zhanghe9704 / tpsa Goto Github PK

openjournals/joss-reviews#4818

I see an issue with the Open Source License (OSL) and the inclusion of non open source code in the repository: include/tpsa.h and src/tpsa.cpp
have been copied from the MAD-X code and are distributed with this repository, licensed under MIT. On the other hand, the two source files are copyright to L. Yang, not licensed under any OSL, and distributors are asked to request L. Yang's consent prior to redistribution. In my view this is not compatible with OS Licensing, certainly not ok to put the entire repo under MIT.

I see these two solutions to the problem
1: Ask L. Yang to release his code under OS License and include or redistribute in this repo
2: Remove L. Yang's code from this repo and instruct users how to obtain it, including request for consent by L. Yang.

In my view this is blocking a release under OSL and violating JOSS' terms of publication.

openjournals/joss-reviews#4818

The installation instructions in the README are fine but the cmake file (CMakeLists.txt) does not specify any dependencies beyondthe minimal cmake version. As observed in #2 , there are e.g. limitations on the gcc-version (gcc<=10 ok, gcc-12 fails).

Also, the tests depend on Catch2 and it remains unclear if that framework is included with the sources or needs to be installed separately.

• Clearly list all dependencies in the README
• Put checks for dependencies and build enviroment (e.g. gcc version) into CMakeLists.txt
• Add third party libraries (e.g. Catch2) as additional build targets into cmake (use cmake's ExternalProject).

I'll be happy to assist with the cmake edits.

This can be fixed by configuring git.
Please refer to https://stackoverflow.com/questions/10418975/how-to-change-line-ending-settings

The code compiles fine with clang++ on Mac with M2 Pro chip and Ventura OS. However the resulting executable crashes with a segmentation fault. Since a lot of researchers use Mac, fixing this would lead to wider adoption of the code.

openjournals/joss-reviews#4818

Community guidelines are missing (beyond the author's contact email). You may want to take advantage of github's instructions (go Insights -> Community Standards -> Contributing) in the repos' menu) and/or consult JOSS's documentation on this topic at https://joss.readthedocs.io/en/latest/review_criteria.html#community-guidelines

When I do cmake install, only the lib is installed and not the header files.

When I run the below commands

cmake -S. -Bbuild -DCMAKE_INSTALL_PREFIX=<install_location>
cd build
make
make install

only the library files are installed at <install_location>/lib and the header files are missing. Header files need to be installed in <install_location>/include when I run the make install command.

Could you please fix this?

JOSS review openjournals/joss-reviews#4818

Please take these as suggestions to improve clarity and readability of the paper

Abstract

• I would remove the part ", based on which more sophisticated methods ..., etc." and put these references into the Background section (citations in abstracts should be self-contained, in any case).
• Instead, add a short statement of need, along the lines of "a reusable implementation of tpsa/da as a modern c++ library or other high level programming language like python is currenty missing or incomplete"

Background

The Background section is excellent, well written, concise and accessible to any non-expert reader. Well done!

• line 34 (page 2) has a typo, should read "limited number of iterations".

Statement of need

• line 44: avoid "etc" to conclude citations. It does not add any information to the reader.
• In general, there are a number of typos and language issues in this section. If possible, please consult a native speaker. AI tools are your friend, too ;)

Features

• line 63: please add a reference or URL to L. Yang's code. Up to which version was it part of MAD-X?

Verification:

• If possible, can you quantify the (average) discrepancy between cosy-infinity and your tpsa/da? e.g. RMS or other distance metric? This would make your assessment more comparable to other tpsa/da implementations.
• Are there any potential/hypothetical applications, where errors as small as 1e-15 or 1e-16 could become important?

In the docs, the minimum C++ language spec is given as C++11. But to compile the examples, C++14 is used. Is the discrepancy due to the usage of C++14 features in examples? Now that all compilers support C++14, I think bumping the minimum spec to C++14 would be a better option.

openjournals/joss-reviews#4818

As mentioned in the README, running the tests produces a segmentation fault although all tests pass.

OS: Debian-12
gcc: 10.2.1

Built tpsa code and test executable according to instructions (README.md).

▶ ./tests
===============================================================================
All tests passed (21 assertions in 3 test cases)

[1]    416166 segmentation fault  ./tests

Although the README says this is a known issue and does not seem to affect the code in production setting, I'd still strongly suggest to fix this. Observing segfaults in a test may keep potential users from adopting the library in their code (at least judging for myself). I guess the root cause lies in the test framework.

Python installation on Ubuntu 22.04 fails because it could not find the file named "README.md". Please rename readme.md to README.md. On Linux, case matters.

openjournals/joss-reviews#4818

Upon first glance, the documentation is limited to the repository top level README.md. There is a doc directory with doxygen content but no instruction how to build it (does it have to be built or is it included with the repo?) how is it maintained if the API changes?

I suggest using some flavor of CI/CD to build the code and the documentation (e.g. github actions and github pages) to make documentation available as a website on its own rather than a local collection of html files.

Doing so would also check the box Documentation - Functionality Documentation (API)

I found a few issues on the python side.

1. Examples:
   a) Unnecessary imports: 01 and 06 don't need to have import pybind11
   statement. Please delete those import statements.
   In the instructions on README.rd, remove the below install instructions. They
   are automatically downloaded when someone installs tpsa with pip.
   bash pip install pybind11 pip install scikit-build-core
   b) Segfaults: 02, 03, 04 are failing with segfaults on Ubuntu 22.04.

2. Carriage return chars in tpsa_python.cc file.

JOSS Review: openjournals/joss-reviews#4818

When compiling the code (tip of master branch as of today), I get

cmake .
-> ok

make

[ 16%] Building CXX object CMakeFiles/tpsaso.dir/src/da.cc.o
In file included from /usr/include/c++/12/complex:41,
                 from /home/grotec/Repositories/JOSSReviews/tpsa/src/../include/da.h:12,
                 from /home/grotec/Repositories/JOSSReviews/tpsa/src/da.cc:9:
/usr/include/c++/12/complex: In instantiation of ‘std::complex<_Tp> std::polar(const _Tp&, const _Tp&) [with _Tp = DAVector]’:
/usr/include/c++/12/complex:778:29:   required from ‘std::complex<_Tp> std::__complex_exp(const complex<_Tp>&) [with _Tp = DAVector]’
/usr/include/c++/12/complex:793:56:   required from ‘std::complex<_Tp> std::exp(const complex<_Tp>&) [with _Tp = DAVector]’
/home/grotec/Repositories/JOSSReviews/tpsa/src/da.cc:1259:49:   required from here
/usr/include/c++/12/complex:703:7: error: no match for ‘operator>=’ (operand types are ‘const DAVector’ and ‘int’)
  703 |       __glibcxx_assert( __rho >= 0 );
      |       ^~~~~~~~~~~~~~~~
...

OS: Debian 12.2 (Kernel 6.1.0-15-amd64)
cmake: 3.25.1
gcc: 12.2.0

JOSS Review: openjournals/joss-reviews#4818

• Berz, M (1999): Journal volume and pages missing
• Deniau et al 2017 is the mad-x reference manual, is there a paper that describes the code? mad-x gh repo has a doi, maybe that's better suited as a citation reference?
• Forest et al 2002: no DOI, could add report number "CERN-SL-2002-044-AP" and/or url https://inspirehep.net/literature/591979
• Makino, Berz 2003: This is weird: I find this pdf: https://www.bmtdynamics.org/pub/papers/GOM05/GOM05.pdf, but it's from 2005 (not 2003), Journal is "Transactions on Computers" (not Int. J. of Computer Research), volume, issue, and pages are off, too. Searching for the given citation, nothing comes back in various citation search engines, except the pdf linked above. Can you clarify, please?
• all other references are fine

The header file location is hard coded in examples/examples.cc.
Line 1 in examples.cc should contain #include "da.h". The location of the header files is then specified in the command line using the -I flag.

The command

gcc examples/examples.cc -o tpsa_exp -I ./include/ -L. -ltpsa -lstdc++ -lm -std=c++14

should be modified to

gcc examples/examples.cc -o tpsa_exp -I<cmake_install_prefix>/include/ -L<cmake_install_prefix>/lib -ltpsa -lstdc++ -lm -std=c++14