[REVIEW]: SyntheticEddyMethod.jl: A Julia package for the creation of inlet flow conditions for LES

[editorialbot]

Submitting author: !--author-handle-->@carlodev<!--end-author-handle-- (Carlo Brunelli) Repository: https://github.com/carlodev/SyntheticEddyMethod.jl Branch with paper.md (empty if default branch): JossSub Version: v0.4.2 Editor: !--editor-->@philipcardiff<!--end-editor-- Reviewers: @atzberg, @akshaysridhar Archive: 10.5281/zenodo.8167205

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/8a5b8b6eec19373a7eb3d154b4d0eed6"><img src="https://joss.theoj.org/papers/8a5b8b6eec19373a7eb3d154b4d0eed6/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/8a5b8b6eec19373a7eb3d154b4d0eed6/status.svg)](https://joss.theoj.org/papers/8a5b8b6eec19373a7eb3d154b4d0eed6)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@atzberg & @akshaysridhar, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @philipcardiff know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @atzberg

📝 Checklist for @akshaysridhar

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.88  T=0.02 s (1287.1 files/s, 140428.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TOML                             3            226              1           1053
Julia                           12            224             97            717
Markdown                         7            183              0            493
YAML                             5              3              6            107
TeX                              1              3              0             50
JSON                             1              0              0              1
-------------------------------------------------------------------------------
SUM:                            29            639            104           2421
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1137/141000671 is OK
- 10.1016/j.ijheatfluidflow.2006.02.006 is OK
- 10.1007/s10494-013-9488-2 is OK
- 10.1016/j.ijheatmasstransfer.2019.02.061 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

Wordcount for paper.md is 656

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[atzberg]

Review checklist for @atzberg

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/carlodev/SyntheticEddyMethod.jl?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@carlodev) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[atzberg]

Overall, the package is well-organized with good discussions of the methods, implementations, and usage. The package provides implementations of simulation methods from the literature for modeling turbulent flows. Below are a few relatively minor items and typos to fix.

In the SyntheticEddyMethod.jl/README.md:

• Small typo to fix "Then, eddies are initialize in the virtualbox... " should be "Then, eddies are initialized in the virtualbox... "

• A little confused by these two sentences "Compute the velocity fluctuation. It is then is 'corrected' using the matrix A which is internally I created using the..." if I understood correctly, I would suggest re-phrasing similar to "For computing the velocity fluctuations, there is a 'correction' using the matrix A which is internally created using the..." (or re-phrase to clarify what was meant by 'corrected').

In the paper.md -> PDF:

• small typo / clarify "...and to control the level of turbulence and eddies length of the generated fields." suggest changing "...and to control the level of turbulence and length-scales of the eddies in the generated fields." (or something similar to clarify 'eddies length')

• "...implementing the divergence-free (DFSEM) constraint at the fluctuations for incompressible flows, as most of the case of turbulence." suggest changing to something similar to "...implementing the divergence-free (DFSEM) constraint to obtain fluctuations for incompressible flows, which are the most common cases studied for turbulence."

• "Julia is extremely expressive and allows one to condensate complex mathematical expression in a few synthetic lines." suggest editing to "Julia is extremely expressive and allows one to condensate complex mathematical expression into a few syntactic lines."

In summary, the package is put together well with good discussions of the implemented methods and on the usage of the APIs. After making the minor edits mentioned above, I recommend accepting for JOSS.

[carlodev]

Dear @atzberg thank you very much for your review and all your comments. I have just fixed the typos and rephrased the sentences you pointed out. I appreciate the effort and the positive feedback.

[philipcardiff]

Thank you, @atzberg , for your comprehensive and prompt review.

@carlodev, thank you for addressing these points; we can now wait for @akshaysridhar 's comments.

[carlodev]

I don't see @akshaysridhar as a participant in this issue

[philipcardiff]

I don't see @akshaysridhar as a participant in this issue

Hi @carlodev , you will see @akshaysridhar listed as a reviewer at the top of this issue.

@akshaysridhar has confirmed to me by email that he can review this submission in the coming 2-3 weeks.

[akshaysridhar]

Review checklist for @akshaysridhar

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/carlodev/SyntheticEddyMethod.jl?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@carlodev) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[akshaysridhar]

SyntheticEddyMethod.jl is a Julia language implementation of methods published in literature that enable easy generation of turbulent inflow profiles. The package is generally well organised, and satisfies the key requirements listed in the review checklist. The accompanying paper is concise, and the listed features are consistent with the code. A few suggestions for improvement are listed below.

Tests

• ]test out of the box run, with 84/84 passing tests in a generic group SyntheticEddyMethod.jl - These tests could be grouped into more useful subsections to allow future contributors to easily identify key components. -[ Info: convecting eddies is a repetitive printed statement when launching test - is this necessary? Can this be condensed into a simpler display statement?
• Please include a statement explaining why this block is commented: https://github.com/carlodev/SyntheticEddyMethod.jl/blob/eca3abb9a4744add104a93cc6297480eed070415/test/read_reynoldsstress.jl#L32-L78 - If this indeed verifies consistency with a "known/provided" profile - perhaps this is better included within a testset block (or as an example).

Documentation

• References section in documentation currently contains API information. I suggest renaming this as such.
• I suggest using https://docs.juliahub.com/DocumenterCitations/B0owD/0.2.2/#Telling-Documenter.jl-about-your-bibliography to document citations using at-cite macro in Julia.
• Small type-error fixes: "referers -> refers", "fluctutation -> fluctuation ", "coeherent -> coherent", "speicific -> specific"

Paper

• Overall, the paper is concise and supports the main code documentation in its descriptions of contributions.
• The text in the results section could be condensed into the figure caption. The block that currently describes the figures could perhaps then be used to highlight advanced use cases.

I believe this submission is suitable for publication following the minor changes listed above!

[philipcardiff]

Thanks @akshaysridhar.

@carlodev, please address the points raised above; feel free to discuss and clarify the points with @akshaysridhar.

[carlodev]

Thank you @akshaysridhar for your insightful comments and suggestions. I have applied all the modifications, feel free to check and verify if I understood your remarks correctly. I also reorganised the test section, and added the commented example.

Concerning the Info: connecting eddies is an indication to the user that Eddies are convected in the VirtualBox. During the testing phase it is printed continuously because the validation/test process is statistics, so a significant number of samples is needed. The statistical validation can take up quite some time, but seeing that statement printed provides feedback about the fact that is running.

[akshaysridhar]

Thanks @carlodev for making the suggested changes. I've checked out the JossSub branch, and have the following suggestions:

• [x] The doc-build with the latest changes results in the following warnings which I believe can be easily fixed by including these functions in the at-docs block in the api info markdown file.

  [ Info: CheckDocument: running document checks.
  ┌ Warning: 2 docstrings not included in the manual:
  │
  │     SyntheticEddyMethod.Reynolds_stress_point :: Tuple{Vector{Float64}, Reynolds_stress_interpolator}
  │     SyntheticEddyMethod.Reynolds_stress_points :: Tuple{Vector{Float64}, Reynolds_stress_interpolator}
  │
  │ These are docstrings in the checked modules (configured with the modules keyword)
  │ that are not included in @docs or @autodocs blocks.

• [x] "coeherent -> coherent" in ./docs/src/index.md:15:- Create coeherent eddies in 3D domain

• [x] "fluctutation -> fluctuation " in ./docs/src/usage.md:84:Now, we are going to evaluate the fluctutations

• [x] In

  21 @testset "ReynoldsStress" begin include("TestDrivers/driver_reynoldsstress.jl")
  22     read_re_test()
  23     test_anystoropic_reynolds()
  24 end 

  -> Should this be anisotropic (and therefore also updated in the corresponding function definition?

• [x] Re [ Info: convecting eddies : I see that in a standard use case this is a single info statement in the compute_fluct function -> I think a combination of @info <statement> maxlog=<integer> with an indicator of the total number of samples collected for the test would be a better option (This would be succinct, and retains the information about the action the code is performing in your above comment).

(Edited to include checklist / issue tracking. )

[carlodev]

Thanks @akshaysridhar for your suggestions. I have fixed the docs warnings, the typos. I also modified the @info macro as you suggest in order to avoid seeing [ Info: convecting eddies so many times

[akshaysridhar]

Thanks @carlodev for making the suggested changes! @philipcardiff I have completed my review at this stage; I'm happy with the responses to the comments above!

[philipcardiff]

@editorialbot check references

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1137/141000671 is OK
- 10.1016/j.ijheatfluidflow.2006.02.006 is OK
- 10.1007/s10494-013-9488-2 is OK
- 10.1016/j.ijheatmasstransfer.2019.02.061 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[philipcardiff]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[philipcardiff]

HI @carlodev , I have proposed a few minor English edits in a pull request: https://github.com/carlodev/SyntheticEddyMethod.jl/pull/20.

Let me know when these have been incorporated.

[philipcardiff]

@carlodev: once you have made the final changes above, please issue a new tagged release of the software (if changed) and archive it (e.g. on Zenodo, figshare, or other). Please then post the version number and archive DOI here.

[akshaysridhar]

@philipcardiff @carlodev Apologies for missing this earlier - but the pdf file doesn't appear to render figure captions correctly - I see that these captions for the two figures are included in the code as :

![Spectra examples at different Turbulent Intensities using tent function as shape function. It refers to the fluctuations in time in one specific point.](images/docs/Spectra.png){ width=50% }
![normalized divergence in a plane using the divergence-free feature. \label{fig:dfsem-plane}](images/docs/Div_free_plane.png){ width=50%  }

[carlodev]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[carlodev]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[carlodev]

Hi @philipcardiff, I have merged your pull request, fixed the rendering error pointed out by @akshaysridhar . I merged the joss folder with the master, published a new version (0.4.2) and it has been archived on zenodo: 10.5281/zenodo.8167205

[philipcardiff]

Hi @carlodev , I made one more typo fix at https://github.com/carlodev/SyntheticEddyMethod.jl/pull/22/files.

[philipcardiff]

@editorialbot set 10.5281/zenodo.8167205 as archive

[editorialbot]

Done! archive is now 10.5281/zenodo.8167205

[carlodev]

Hi @philipcardiff , thanks for the typo fix, I have merged your pull request

[philipcardiff]

@editorialbot set v0.4.2 as version

[editorialbot]

Done! version is now v0.4.2

[philipcardiff]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1137/141000671 is OK
- 10.1016/j.ijheatfluidflow.2006.02.006 is OK
- 10.1007/s10494-013-9488-2 is OK
- 10.1016/j.ijheatmasstransfer.2019.02.061 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[philipcardiff]

Hi @kyleniemeyer, this paper is ready for processing.

[editorialbot]

:wave: @openjournals/pe-eics, this paper is ready to be accepted and published.

Check final proof :point_right::page_facing_up: Download article

If the paper PDF and the deposit XML files look good in https://github.com/openjournals/joss-papers/pull/4421, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[philipcardiff]

Hi @carlodev, please perform one last check of the article proof, and let me know if you find any issues.

[carlodev]

I have checked it, and changed a capital letter in a figure caption

[philipcardiff]

@editorialbot recommend-accept

[editorialbot]

Attempting dry run of processing paper acceptance...

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1137/141000671 is OK
- 10.1016/j.ijheatfluidflow.2006.02.006 is OK
- 10.1007/s10494-013-9488-2 is OK
- 10.1016/j.ijheatmasstransfer.2019.02.061 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

:wave: @openjournals/pe-eics, this paper is ready to be accepted and published.

Check final proof :point_right::page_facing_up: Download article

If the paper PDF and the deposit XML files look good in https://github.com/openjournals/joss-papers/pull/4422, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

[kyleniemeyer]

Looks good to me!

[kyleniemeyer]

@editorialbot accept

[editorialbot]

Doing it live! Attempting automated processing of paper acceptance...