diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 7bc2b1e989..f8328cff74 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -27,7 +27,7 @@ Format: - job: assign_to_board - Assigns issues and PRs to either Content Development board or BSSw Internal board based on labels ("content: *" or "scope: site-internal") * notify-external-contrib.yml (Notify external contributions) - - https://github.com/betterscientificsoftware/bssw.io/blob/0e1ba1664239ab6097e903f8bb94fef08576f103/.github/workflows/notify-external-contrib.yml#L6-L12 + - - job: notify-external-contributions - Label and send email to bssw-editorial-list for externally opened issues, prs and discussions diff --git a/.github/workflows/check-urls.yml b/.github/workflows/check-urls.yml new file mode 100644 index 0000000000..04abea815a --- /dev/null +++ b/.github/workflows/check-urls.yml @@ -0,0 +1,161 @@ +name: Check URLs + +on: + workflow_dispatch: + schedule: + - cron: '17 5 * * 0' # 5:17 AM every Sunday + pull_request: + branches: [ main ] +env: + ignore_file_patterns: | + docs + images + utils + Events + +jobs: + check-urls: + runs-on: ubuntu-latest + + steps: + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.9' + + - name: Install dependencies + run: | + python -m pip --no-cache-dir --disable-pip-version-check install --upgrade pip + python -m pip --no-cache-dir --disable-pip-version-check install linkchecker + + - name: Reformat environment variables + id: setup_vars + run: | + tmp=$(echo "${{ env.ignore_file_patterns }}" | tr '\n' ' ') + echo "ignore_file_patterns=$tmp" >> $GITHUB_OUTPUT + + - name: Checkout Repo for PR branch + if: ${{ github.event_name == 'pull_request' }} + uses: actions/checkout@v4 + + - name: Checkout Repo for link check + if: ${{ github.event_name != 'pull_request' }} + uses: actions/checkout@v4 + with: + ref: 'sched-link-checks' + + - name: Sync main to link check branch + if: ${{ github.event_name != 'pull_request' }} + run: | + git config user.name 'github-actions' + git config user.email 'github-actions@github.com' + git fetch origin main + git merge origin/main --no-edit -X thiers + git push origin sched-link-checks + + - name: Get Changed Files (for PRs) + if: ${{ github.event_name == 'pull_request' }} + id: changed-files + uses: tj-actions/changed-files@v42 + with: + separator: ' ' + + - name: Generate lists of files to check and ignore + id: file_list + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + echo "files=${{ steps.changed-files.outputs.all_changed_files }}" >> $GITHUB_OUTPUT + echo "ignore_file_patterns=" >> $GITHUB_OUTPUT + else + echo "files=" >> $GITHUB_OUTPUT + echo "ignore_file_patterns=${{ steps.setup_vars.outputs.ignore_file_patterns }}" >> $GITHUB_OUTPUT + fi + + - name: Check URLs in selected files + run: | + for f in ${{ steps.file_list.outputs.files }}; do + if [ "${f##*.}" != "md" ]; then + continue + fi + for ef in ${{ steps.file_list.outputs.ignore_file_patterns }}; do + if [ "$ef" = "$f" ]; then + continue 2 # ignore this file + fi + fd=$(echo $f | cut -d'/' -f1) + if [ "$ef" = "$fd" ]; then + continue 2 # ignore this dir + fi + done + linkchecker -f utils/LinkChecker/.linkcheckerrc file://$(pwd)/$f >> linkchecker.out || true + cat linkchecker.out >> linkchecker-all.out + done + + - name: Process log + run: | + python utils/LinkChecker/cklcresults.py ${{ github.event_name }} + + - name: Upload artifact + if: ${{ github.event_name == 'pull_request' }} + uses: actions/upload-artifact@v4 + with: + name: bad-links + path: bad_links.txt + + - name: Update link logs + if: ${{ github.event_name != 'pull_request' }} + run: | + git commit -m 'Update link logs' + git push origin sched-link-checks + +# +# Keep the recurring failures and definitely bad lists in repo on +# branch manage-broken-links +# +# Download those files before startin +# +# If a link "works" (200) remove it from "recurring failures" list +# If a link "does not work" (!= 200) +# - if it is already on recurring failures list +# - if it is too old, flag it as "definitely bad", else nothing +# +# - if it is not already on persistent failures list, add it to "new" and "persistent failures" list and date it + +# +# Upload the recurring failures and definitely bad lists to somehwere +# Report success if definitely bad list is empty, otherwise failure +# generate email with links or actual data +# +# you have to use file:// on command-line to checker + +# bare URLs in markdown are not actually links and will not be checked. Many +# markdown renderers and browsers will recognize these and handle them as links +# but that is by convention only. There is no markdown standard for how bare +# URLs in markdown are handled. The only standard is to enclose them in `<` and +# `>` chars. + +# +# Description: +# +# Triggers in one of three ways; 1) manually, 2) scheduled weekly Sunday's 5:17 AM +# or 3) pull request +# +# Stores ignore pattern cases in env. variables and then reformats those (because +# they have newlines) into a comma-separated single line string that can be digested +# as inputs to other actions. +# +# For PRs, uses changed-files action to get list of changed files and passes this +# to urlchecker via `include_files param. Also, ignore file patterns is set to +# empty string for PRs because we think URLs anywhere in PRs should be checked. +# +# For scheduled or manual triggers, uses fact that empty `include_files` param +# causes urlchecker to process *all* files that match in `file_type` param but do +# not match any `exclude_files` patterns. These file patterns for exclude work +# more or less like file globs. So, specifying the initial part of the string +# for a file (path) name is sufficient to ignore the file. +# +# We include Events in file patterns to ignore because of all content we host, +# we suspect Event URLs are the most likely to go stale rather quickly **and** because +# the URL validness is important only during the short window prior to the event. +# That said, we don't want to ignore Events in PRs and we do not as per above. +# diff --git a/Articles/Blog/2020-01-usrse.md b/Articles/Blog/2020-01-usrse.md index 6045135e7f..6996384122 100644 --- a/Articles/Blog/2020-01-usrse.md +++ b/Articles/Blog/2020-01-usrse.md @@ -31,9 +31,7 @@ fundamental part of their work. In the United States and globally, over the past two to three years (except the UK, which seems to be a few years ahead of the trend), the use of the term RSE has exploded. The RSE role was formally recognized in 2019 by the European Commission in a report -“[Recognising the Importance of Software in Research - Research Software -Engineers (RSEs), a UK -Example](https://ec.europa.eu/info/sites/info/files/research_and_innovation/importance_of_software_in_research.pdf)” +“[Recognising the Importance of Software in Research - Research Software Engineers (RSEs), a UK Example](https://op.europa.eu/s/yA6b)” and by UNESCO in the report “[Paris Call: Software Source Code as Heritage for Sustainable Development](https://en.unesco.org/foss/paris-call-software-source-code)”. As an diff --git a/Articles/Blog/2020-11-PSIP4HDF5.md b/Articles/Blog/2020-11-PSIP4HDF5.md index 12967ce3a0..453704860a 100644 --- a/Articles/Blog/2020-11-PSIP4HDF5.md +++ b/Articles/Blog/2020-11-PSIP4HDF5.md @@ -55,7 +55,7 @@ In April of 2020, the [LLNL WSC](https://wci.llnl.gov/about-us/weapon-simulation-and-computing) Research Coordination Council established a $150K contract with [The HDF Group](https://www.hdfgroup.org) (THG), the organization responsible for developing and maintaining -[HDF5](https://portal.hdfgroup.org/display/HDF5/HDF5), to employ PSIP to effect some +[HDF5](https://docs.hdfgroup.org/hdf5/develop/index.html), to employ PSIP to effect some software process improvement goals (IGs). Interested readers are welcome to read the [full report](https://www.osti.gov/biblio/1698291-psip-hdf5pilot-project-final-report). @@ -101,7 +101,7 @@ and create PTCs: * **Improvement Goal #3 (IG3)**: Define and adopt a set of consistent coding standards ([PTC](https://bssw-psip.github.io/ptc-catalog/catalog/THGCodingStandards.html)) THG staff members then self-organized around the IG(s) they were passionate about drafting and refining -PTCs (see images below). Developing quality [PTCs](https://bssw-psip.github.io/practice-guides/how_to_create_ptc.html) +PTCs (see images below). Developing quality [PTCs](https://bssw-psip.github.io/practice-guides/pages/how_to_create_ptc.html) is essential but also nontrivial. It can require facilitation by an experienced but objective third party. The challenge is in ensuring that each step has a good definition of "done" and also represents a value-added improvement in diff --git a/Articles/Blog/2021-09-CollegevilleReportDay1.md b/Articles/Blog/2021-09-CollegevilleReportDay1.md index 3a1818affc..47edbedea4 100644 --- a/Articles/Blog/2021-09-CollegevilleReportDay1.md +++ b/Articles/Blog/2021-09-CollegevilleReportDay1.md @@ -6,7 +6,7 @@ - -#### Contributed by: [Cody Balos](https://github.com/balos1), [Jed Brown](https://github.com/jedbrown), [Gerasimos Chourdakis](https://github.com/MakisH), [Ben Cowan](https://github.com/benc303), [Anshu Dubey](https://github.com/adubey64), [Vadim Dyadechko](https://github.com/vdayadechko), [Robert Jacob](https://github.com/rljacob), [Sarah Knepper](https://github.com/sknepper), [Jay Lofstead](https://github.com/gflofst), [Lois Curfman McInnes](https://github.com/curfman), [Reed Milewicz](https://github.com/rmmilewi), [Jacob Moxley](https://github.com/jmox0351), [Todd Munson](https://github.com/tmunson), [Sarah Osborn](https://github.com/osborn9), [Jim Pivarski](https://github.com/jpivarski), [Elaine Raybourn](https://github.com/elainraybourn), [Barry Smith](https://github.com/BarrySmith), [James Willenbring](https://github.com/jwillenbring), [Ulrike Meier Yang](https://github.com/ulrikeyang), [Sam Yates](https://github.com/halfflat), [Michael A. Heroux](https://github.com/maherou), and [Johanna Cohoon](https://github.com/jlcohoon) +#### Contributed by: [Cody Balos](https://github.com/balos1), [Jed Brown](https://github.com/jedbrown), [Gerasimos Chourdakis](https://github.com/MakisH), [Ben Cowan](https://github.com/benc303), [Anshu Dubey](https://github.com/adubey64), [Vadim Dyadechko](https://github.com/vdyadechko), [Robert Jacob](https://github.com/rljacob), [Sarah Knepper](https://github.com/sknepper), [Jay Lofstead](https://github.com/gflofst), [Lois Curfman McInnes](https://github.com/curfman), [Reed Milewicz](https://github.com/rmmilewi), [Jacob Moxley](https://github.com/jmox0351), [Todd Munson](https://github.com/tmunson), [Sarah Osborn](https://github.com/osborn9), [Jim Pivarski](https://github.com/jpivarski), [Elaine Raybourn](https://github.com/elaineraybourn), [Barry Smith](https://github.com/BarrySmith), [James Willenbring](https://github.com/jwillenbring), [Ulrike Meier Yang](https://github.com/ulrikeyang), [Sam Yates](https://github.com/halfflat), [Michael A. Heroux](https://github.com/maherou), and [Johanna Cohoon](https://github.com/jlcohoon) #### Publication date: September 20, 2021 diff --git a/Articles/Blog/2021-12-sc21-swe-cse-bof.md b/Articles/Blog/2021-12-sc21-swe-cse-bof.md index cd481e4720..d335c5a101 100644 --- a/Articles/Blog/2021-12-sc21-swe-cse-bof.md +++ b/Articles/Blog/2021-12-sc21-swe-cse-bof.md @@ -4,7 +4,7 @@ - -#### Contributed by: [David E. Bernholdt](https://github.com/bernhold), [Michael Bader](https://github.com/baderml), Michelle Barker, Ben Brown, [Anshu Dubey](https://github.com/adubey64), [Nasir Eisty](https://github.com/neistyS), [Sandra Gesing](https://github.com/sandragesing), [Patricia Grubel](https://github.com/pagrubel), [Rinku Gupta](https://github.com/rinkug), [Michael A. Heroux](https://github.com/maherou), [Saswata Hier-Majumder](https://github.com/sashgeophysics), [Axel Huebl](https://github.com/ax3l), [Mozhgan Kabiri Chimeh](https://github.com/mozhgan-kch), [Daniel S. Katz](https://github.com/danielskatz), [Tomislav Maric](https://github.com/tmaric), [Lois Curfman McInnes](https://github.com/curfman), Bill Miller, [Manish Parashar](https://github.com/parasharmanish), [Ulf D. Schiller](https://github.com/uschille), [Jean Sexton](https://github.com/jmsexton03), [Peter Vaillancourt](https://github.com/sk8forether), Marion Weinzierl, [Yo Yehudi](https://github.com/yochannah) +#### Contributed by: [David E. Bernholdt](https://github.com/bernhold), [Michael Bader](https://github.com/baderml), Michelle Barker, Ben Brown, [Anshu Dubey](https://github.com/adubey64), [Nasir Eisty](https://github.com/neisty), [Sandra Gesing](https://github.com/sandragesing), [Patricia Grubel](https://github.com/pagrubel), [Rinku Gupta](https://github.com/rinkug), [Michael A. Heroux](https://github.com/maherou), [Saswata Hier-Majumder](https://github.com/sashgeophysics), [Axel Huebl](https://github.com/ax3l), [Mozhgan Kabiri Chimeh](https://github.com/mozhgan-kch), [Daniel S. Katz](https://github.com/danielskatz), [Tomislav Maric](https://github.com/tmaric), [Lois Curfman McInnes](https://github.com/curfman), Bill Miller, [Manish Parashar](https://github.com/parasharmanish), [Ulf D. Schiller](https://github.com/uschille), [Jean Sexton](https://github.com/jmsexton03), [Peter Vaillancourt](https://github.com/sk8forether), Marion Weinzierl, [Yo Yehudi](https://github.com/yochannah) #### Publication date: December 21, 2021 @@ -16,12 +16,12 @@ We’ve settled on a format for the BoF that includes 3-minute lightning talks, We had six lightning talks this year, covering a wide range of topics with speakers from the US, UK, Germany, and Australia. -* [Ecosystems are the Future!](https://betterscientificsoftware.github.io/swe-cse-bof/2021-11-sc21-bof/01-brown-ecosystems.pdf) by Benjamin Brown (Office of Advanced Scientific Computing Research (ASCR), Office of Science, U.S. Dept. of Energy). Ben discussed the importance of ecosystems in his vision for the future of the ASCR high performance computing and networking user facilities ([ALCF](https://www.alcf.anl.gov/), [NERSC](https://www.nersc.gov/), [OLCF](https://www.olcf.ornl.gov/), and[ ESnet](https://www.es.net/)) and highlighted scientific software as one of the key ecosystems. He closed with the message “Software ecosystems are research infrastructure!” +* [Ecosystems are the Future!](https://betterscientificsoftware.github.io/swe-cse-bof/assets/2021-11-sc21-bof/01-brown-ecosystems.pdf) by Benjamin Brown (Office of Advanced Scientific Computing Research (ASCR), Office of Science, U.S. Dept. of Energy). Ben discussed the importance of ecosystems in his vision for the future of the ASCR high performance computing and networking user facilities ([ALCF](https://www.alcf.anl.gov/), [NERSC](https://www.nersc.gov/), [OLCF](https://www.olcf.ornl.gov/), and [ESnet](https://www.es.net/)) and highlighted scientific software as one of the key ecosystems. He closed with the message “Software ecosystems are research infrastructure!” * [Open Source for Researchers](https://doi.org/10.5281/zenodo.5655022) by Yo Yehudi (Wellcome Trust). Yo encouraged us to up our game for our open source software projects, making them more open and more accessible to others. She touched on readme files, roadmaps, contributor guides, codes of conduct, a requested citation, contact information, and using an issue tracker and also suggested some resources to help folks get started contributing to open source software. -* [The Internat. CSE Master Program at TUM](https://betterscientificsoftware.github.io/swe-cse-bof/2021-11-sc21-bof/03-bader-masterprogram.pdf) by Michael Bader (Technical University of Munich, TUM). Michael described the International Master’s program in Computational Science and Engineering, which has been offered at TUM since 2001, currently serving approximately 50 students per year. The 4-semester program combines classes in computer science, numerical analysis, and scientific computing - with one of the key challenges being how to guide students from various backgrounds towards becoming experts in software development for supercomputing applications. -* [Senior Level RSE career paths (with an s)](https://betterscientificsoftware.github.io/swe-cse-bof/2021-11-sc21-bof/04-katz-seniorrse.pdf) by Daniel S. Katz (University of Illinois at Urbana-Champaign). Dan presented ideas to help define paths for career progression for research software engineers (RSEs), looking particularly at offering a richer set of opportunities at senior levels to allow RSEs to explore different roles, emphasizing different skills. -* [FAIR 4 Research Software (FAIR4RS)](https://betterscientificsoftware.github.io/swe-cse-bof/2021-11-sc21-bof/05-barker-fair4rs.pdf) by Michelle Barker (Research Software Alliance). Michelle presented the emerging idea of applying the FAIR principles (findability, accessibility, interoperability, reusability) to research software, noting “Software is not just another type of data.” The Research Data Alliance, FORCE11, and the Research Software Alliance are working together to develop the FAIR4RS principles and guidelines for implementing them. -* [Highlights from the IEEE CS Ad Hoc Committee on Open Science & Reproducibility](https://betterscientificsoftware.github.io/swe-cse-bof/2021-11-sc21-bof/06-parashar-openscience.pdf) by Manish Parashar (University of Utah). In 2019, the National Academies of Science, Engineering, and Medicine (NASEM) published a report on Reproducibility and Replicability in Science. Manish described work by the IEEE Computer Society, building upon the NASEM report, to develop an action plan to improve and recognize reproducibility in the society’s publications, conferences, and through its technical committees. +* [The Internat. CSE Master Program at TUM](https://betterscientificsoftware.github.io/swe-cse-bof/assets/2021-11-sc21-bof/03-bader-masterprogram.pdf) by Michael Bader (Technical University of Munich, TUM). Michael described the International Master’s program in Computational Science and Engineering, which has been offered at TUM since 2001, currently serving approximately 50 students per year. The 4-semester program combines classes in computer science, numerical analysis, and scientific computing - with one of the key challenges being how to guide students from various backgrounds towards becoming experts in software development for supercomputing applications. +* [Senior Level RSE career paths (with an s)](https://betterscientificsoftware.github.io/swe-cse-bof/assets/2021-11-sc21-bof/04-katz-seniorrse.pdf) by Daniel S. Katz (University of Illinois at Urbana-Champaign). Dan presented ideas to help define paths for career progression for research software engineers (RSEs), looking particularly at offering a richer set of opportunities at senior levels to allow RSEs to explore different roles, emphasizing different skills. +* [FAIR 4 Research Software (FAIR4RS)](https://betterscientificsoftware.github.io/swe-cse-bof/assets/2021-11-sc21-bof/05-barker-fair4rs.pdf) by Michelle Barker (Research Software Alliance). Michelle presented the emerging idea of applying the FAIR principles (findability, accessibility, interoperability, reusability) to research software, noting “Software is not just another type of data.” The Research Data Alliance, FORCE11, and the Research Software Alliance are working together to develop the FAIR4RS principles and guidelines for implementing them. +* [Highlights from the IEEE CS Ad Hoc Committee on Open Science & Reproducibility](https://betterscientificsoftware.github.io/swe-cse-bof/assets/2021-11-sc21-bof/06-parashar-openscience.pdf) by Manish Parashar (University of Utah). In 2019, the National Academies of Science, Engineering, and Medicine (NASEM) published a report on Reproducibility and Replicability in Science. Manish described work by the IEEE Computer Society, building upon the NASEM report, to develop an action plan to improve and recognize reproducibility in the society’s publications, conferences, and through its technical committees. ### Breakout discussions diff --git a/Articles/Blog/ConnectingSoftwareDevelopers.md b/Articles/Blog/ConnectingSoftwareDevelopers.md index f4568584fd..4ce771ddbf 100644 --- a/Articles/Blog/ConnectingSoftwareDevelopers.md +++ b/Articles/Blog/ConnectingSoftwareDevelopers.md @@ -56,8 +56,7 @@ More details about these two events can be found on the [ORNL Software Expo web Gregory Watson is a Senior Research Scientist in the Research Software Engineering Group at Oak Ridge National Laboratory. He completed his Ph.D. in Computer Science in 2000 from Monash University. Dr. Watson's research interests include software engineering practices, development environments, programming tools, and modeling and simulation tools for high performance and scientific computing. He is founder of the Eclipse Parallel Tools Platform, and project leader of the Eclipse Science Top Level Project. - -Elsa Gonsiorowski is an HPC I/O Specialist working at Lawrence Livermore National Laboratory. She graduated with her Ph.D. in Computer Science in 2016 from Rensselaer Polytechnic Institute. Elsa works on a number of open source, system software tools to support HPC users as they manage files across an increasingly complex storage hierarchy. She has a passion for useful documentation and CMake. +Elsa Gonsiorowski is an HPC I/O Specialist working at Lawrence Livermore National Laboratory. She graduated with her Ph.D. in Computer Science in 2016 from Rensselaer Polytechnic Institute. Elsa works on a number of open source, system software tools to support HPC users as they manage files across an increasingly complex storage hierarchy. She has a passion for useful documentation and CMake. ### References -* 1[CDC guidance on CV-19 transmission](https://www.cdc.gov/coronavirus/2019-ncov/about/transmission.html) +* 1[CDC guidance on CV-19 transmission](https://www.cdc.gov/coronavirus/2019-ncov/your-health/about-covid-19.html) * 2[WHO summary remarks of COVID-19](https://www.who.int/health-topics/coronavirus) * 3[NIH CV-229E surface study](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4659470/) * 4[Aerosol and surface stability of SARS-CoV-2 compared with SARS-CoV-1](https://www.medrxiv.org/content/10.1101/2020.03.09.20033217v2.full.pdf) * 5[Surface study of various coronaviruses](https://www.journalofhospitalinfection.com/article/S0195-6701(20)30046-3/fulltext) -* 6[CDC guidance on cleaning surfaces](https://www.cdc.gov/coronavirus/2019-ncov/community/organizations/cleaning-disinfection.html#How%20to%20Clean%20and%20Disinfect) +* 6[CDC guidance on cleaning surfaces](https://www.cdc.gov/mmwr/volumes/69/wr/mm6923e2.htm) * 7[CDC description of transmission scenario](https://www.cdc.gov/coronavirus/2019-ncov/about/prevention.html?CDC_AA_refVal=https%3A%2F%2Fwww.cdc.gov%2Fcoronavirus%2F2019-ncov%2Fabout%2Fprevention-treatment.html) * 8[Wikipedia summary of coronavirus](https://en.wikipedia.org/wiki/Coronavirus) * 9[CDC explains names SARS-CoV-2 and COVID-19](https://www.who.int/emergencies/diseases/novel-coronavirus-2019/technical-guidance/naming-the-coronavirus-disease-(covid-2019)-and-the-virus-that-causes-it) -* 10[CDC describes higher risk persons](https://www.cdc.gov/coronavirus/2019-ncov/specific-groups/high-risk-complications.html) +* 10[CDC describes higher risk persons](https://www.cdc.gov/coronavirus/2019-ncov/need-extra-precautions/people-with-medical-conditions.html) * 11[Asymptomatic transmission of COVID-19](https://jamanetwork.com/journals/jama/fullarticle/2762028) * 12[Explanation of the term Fomite](https://en.wikipedia.org/wiki/Fomite) -* 13[CDC guidance on fomite transmission](https://www.cdc.gov/coronavirus/2019-ncov/prepare/cleaning-disinfection.html?CDC_AA_refVal=https%3A%2F%2Fwww.cdc.gov%2Fcoronavirus%2F2019-ncov%2Fcommunity%2Fhome%2Fcleaning-disinfection.html) +* 13[CDC guidance on fomite transmission](https://stacks.cdc.gov/view/cdc/104762) * 14[Best disinfecting wipes](https://learningregistry.org/reviews/best-disinfectant-wipes) * 15[Best practices for cleaning electronics](https://www.pcmag.com/how-to/how-to-spring-clean-your-electronics) * 16[Apple guidance on 70% alcohol](https://support.apple.com/en-us/HT204172?mod=article_inline) diff --git a/Articles/Blog/HowToEnablePerformancePortability.md b/Articles/Blog/HowToEnablePerformancePortability.md index 3ca0ea2821..f034f51ada 100644 --- a/Articles/Blog/HowToEnablePerformancePortability.md +++ b/Articles/Blog/HowToEnablePerformancePortability.md @@ -32,14 +32,22 @@ A composable code is one that can select and combine existing components in the Many numerical technologies are available as libraries, many of which have portable performance. Libraries are also becoming more interoperable with one another. ### Programming Model Choice +<<<<<<< HEAD:Articles/HowTos/HowToEnablePerformancePortability.md +Several tools and programming environments are at various levels of maturity in providing options for portability. For example, *[OpenCL](https://www.khronos.org/opencl)* offers portability across GPU hardware, OS software, and multicore processors; but it does not offer performance portability (see study [here](https://ieeexplore.ieee.org/document/5482576)). Similarly *[OpenMP](http://openmp.org/)* has been a mainstay in hybrid or hierarchical parallelism. It can provide some degree of performance portability but with nontrivial effort in designing parallelism. *[OpenACC 2.0](http://www.openacc.org/)* is a directive-based programming standard, which can generate OpenCL and CUDA code. *[Kokkos](http://www.sciencedirect.com/science/article/pii/S0743731514001257)* and *[RAJA](https://e-reports-ext.llnl.gov/pdf/782261.pdf)* use C++ metaprogramming to provide performance-portable programming models. Tiling abstractions such as *[TiDA](http://sc13.supercomputing.org/sites/default/files/WorkshopsArchive/pdfs/wp118s1.pdf)* provide a way of incorporating hierarchical parallelism. Some domains and codes have taken the approach of domain-specific languages (DSLs); examples are *[OP2](https://people.maths.ox.ac.uk/gilesm/files/InPar_OP2.pdf)* for unstructured meshes and stencil-based languages such as *[Stella](http://adsabs.harvard.edu/abs/2014EGUGA..16.8464G)* and Nebo (see also *[Physis](http://dl.acm.org/citation.cfm?id=2063398)*). Another approach for providing performance portability is taken by task-based programming models such as *[Charm++](http://charm.cs.illinois.edu/papers/07-04)* and *[Parallex](https://ieeexplore.ieee.org/document/5364511)*, which are independent of the number of processors, automate resource management, and support concurrent composition. +======= Several tools and programming environments are at various levels of maturity in providing options for portability. For example, *[OpenCL](https://www.khronos.org/opencl)* offers portability across GPU hardware, OS software, and multicore processors; but it does not offer performance portability. Similarly *[OpenMP](https://www.openmp.org/)* has been a mainstay in hybrid or hierarchical parallelism. It can provide some degree of performance portability but with nontrivial effort in designing parallelism. *[OpenACC 2.0](https://www.openacc.org/)* is a directive-based programming standard, which can generate OpenCL and CUDA code. *[Kokkos](https://www.sciencedirect.com/science/article/pii/S0743731514001257)* and *[RAJA](https://www.osti.gov/servlets/purl/1169830)* use C++ metaprogramming to provide performance-portable programming models. Tiling abstractions such as *[TiDA](https://sc13.supercomputing.org/sites/default/files/WorkshopsArchive/pdfs/wp118s1.pdf)* provide a way of incorporating hierarchical parallelism. Some domains and codes have taken the approach of domain-specific languages (DSLs); examples are *[OP2](https://people.maths.ox.ac.uk/gilesm/files/InPar_OP2.pdf)* for unstructured meshes and stencil-based languages such as *[Stella](https://adsabs.harvard.edu/abs/2014EGUGA..16.8464G)* and Nebo (see also *[Physis](https://dl.acm.org/citation.cfm?id=2063398)*). Another approach for providing performance portability is taken by task-based programming models such as *[Charm++](https://charm.cs.illinois.edu/papers/07-04)* which are independent of the number of processors, automate resource management, and support concurrent composition. +>>>>>>> main:Articles/Blog/HowToEnablePerformancePortability.md ### Dealing with Existing Large Code Base The most important step is to know - before starting the refactoring - the final objective in terms of how deep the changes are going to be. The next step is to profile the code in order to find the hot spots and, if possible, to create a performance model that will help estimate possible performance improvements and help make a decision on the first target kernels to be refactored. One should then look for the best match among the available abstractions. Having a good test suite before starting refactoring is critical. The test suite should not depend on bitwise no-change tests. If possible the test suite should also monitor performance. Also important is having a strategy for verifying intermediate stages of refactoring, because waiting until the whole code is refactored (sometimes called “on-ramping”) will make verification of correctness and performance much more difficult and time consuming. ### FAQs: **Q: How do I choose which programming model to use in my application?** +<<<<<<< HEAD:Articles/HowTos/HowToEnablePerformancePortability.md +**A:** That depends on the target architecture and whether you want to be able to run on multiple platforms. At present not all programming models are compatible with all languages, so that might be another constraint. See [here](https://www.osti.gov/servlets/purl/1306099) and [here](http://dx.doi.org/10.1177/1094342012462751) for examples. **(I’d prefer to see something specific rather than “here and here” - perhaps, See examples with a mesh smoothing algorithm and with a spectral-element-based code.)** +======= **A:** That depends on the target architecture and whether you want to be able to run on multiple platforms. At present not all programming models are compatible with all languages, so that might be another constraint. See an example with a [spectral-element-based code](https://dx.doi.org/10.1177/1094342012462751). +>>>>>>> main:Articles/Blog/HowToEnablePerformancePortability.md **Q: When should I use libraries for performance portability?** **A:** If the bulk of your computation time is spent in solvers that are available from a library, you should consider using it, even if you have to adjust your data structures. You are likely to get state-of-the-art performance portability and better-quality solutions. diff --git a/Articles/Blog/HowToWriteGoodDocumentation.md b/Articles/Blog/HowToWriteGoodDocumentation.md index 6650ef8420..e5b14c09f4 100644 --- a/Articles/Blog/HowToWriteGoodDocumentation.md +++ b/Articles/Blog/HowToWriteGoodDocumentation.md @@ -36,11 +36,20 @@ For a large team with a transient developer population and a long-lived software Use of literate programming is a really good way to produce user level documentation. This approach allows text for manual pages be embedded directly into the source code files and not in separate locations, and workflow for documentation can be integrated into the workflow for development and use. The same is true of inlined informative documentation about the implementation choices. The options for embedded user’s documentation include Doxygen, NDoc, javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, and [TwinTex](https://en.wikipedia.org/wiki/TwinText). A particular challenge exists for writers of Fortran codes, because there isn’t really a good option for automatic generation of manual pages. ROBODoc comes the closest. ### Examples of documentation in scientific software projects: +<<<<<<< HEAD:Articles/HowTos/HowToWriteGoodDocumentation.md +* https://bitbucket.org/pflotran/pflotran-dev/wiki/Home +* http://yt-project.org/doc/ +* https://petsc.org/release/ +* https://flash.rochester.edu/site/flashcode/user_support/ +* http://www.cactuscode.org/documentation/index.html + +======= * https://bitbucket.org/pflotran/pflotran * https://yt-project.org/doc/ * https://www.mpich.org/documentation/guides/ * https://flash.rochester.edu/site/flashcode/user_support/ * +>>>>>>> main:Articles/Blog/HowToWriteGoodDocumentation.md ### References [1] http://martinfowler.com/bliki/TechnicalDebt.html diff --git a/Articles/Blog/URSSI.md b/Articles/Blog/URSSI.md index 4198df5acf..a4467a1aa6 100644 --- a/Articles/Blog/URSSI.md +++ b/Articles/Blog/URSSI.md @@ -61,7 +61,7 @@ in URSSI. ### Collaboration We are not working in a vacuum, but with other like-minded projects. In addition to [Better Scientific Software (BSSw)](https://bssw.io/) and activities around research facilitators -([ACI-REF](https://aciref.org/)) in the United States, there are two ongoing institutes in +([ACI-REF](https://aci-ref.github.io)) in the United States, there are two ongoing institutes in [science gateways (SGCI)](https://sciencegateways.org/) and [molecular sciences (MolSSI)](http://molssi.org/); a recently completed [conceptualization in high energy physics (S2I2-HEP)](http://s2i2-hep.org/); two other conceptualization projects now under way in [geospatial software](http://gsi.cigi.illinois.edu) and diff --git a/CuratedContent/GoodEnoughPracticesInScientificComputing.md b/CuratedContent/GoodEnoughPracticesInScientificComputing.md index 816d21384f..91a3b5bf5f 100644 --- a/CuratedContent/GoodEnoughPracticesInScientificComputing.md +++ b/CuratedContent/GoodEnoughPracticesInScientificComputing.md @@ -52,7 +52,7 @@ thousands of participants in Software Carpentry and Data Carpentry workshops. See: * [Software Carpentry](http://software-carpentry.org) -* [Data Carpentry](http://data-carpentry.org) +* [Data Carpentry](https://datacarpentry.org)