Update ReadMe of ufs-coastal

[saeed-moghimi-noaa]

Description

There was request to include more information on the ReadMe

Solution

Bring some of the information from CoastalApp ReadMe.

Information like:

• Introduction
• Clear status and plans
• Models / component developers
• Organization / Responsibility
• Contributing
• Citations
• !?

[janahaddad]

A problem with modifying the readme in this repo is that it will constantly show a conflict when syncing with the upstream ufs-weathermodel fork. @pvelissariou1 and I will meet to discuss a solution. I'll look at ignoring readme when running git fetch or git pull

[janahaddad]

This is old but might be a solution: https://stackoverflow.com/questions/25315687/ignore-specific-files-when-pulling-from-forked-upstream-origin/25315991#25315991

...not sure if practical

[pvelissariou1]

A draft README file (started from CoastalApp) is at the cmmb branch of UFS-Coastal (https://github.com/oceanmodeling/ufs-coastal/tree/cmmb). Also, there is a licence file that needs to be modified. We might use some material from the original README file (from ufs weather model). Will work on this branch before merging the changes to the main branch.

[pvelissariou1]

Regarding UFS-Coastal and UFS weather model pulls, we need to establish a strategy on how to do this, and what to fetch from wather model.

[saeed-moghimi-noaa]

Sample introduction for ufs-coastal readme

UFS-COASTAL open source code infrastructure forked from UFS-Weather-Model and its downstream applications (ufs-coastal-apps) is being developed as the next generation NOAA’s National Ocean Service (NOS) Coastal Ocean Modeling infrastructure. NOS is partnering with the Oceanic and Atmospheric Research (OAR), National Weather Service (NWS) and coastal ocean modeling community to develop UFS-Coastal to be integrated into the Unified Forecast System modeling portfolio.

[pvelissariou1]

@saeed-moghimi-noaa and its downstream applications (ufs-coastal-apps); what are the ufs-coastal-apps?

[saeed-moghimi-noaa]

ufs-coastal executable within a workflows to constitute an application(s):

• stofs
• necofs
• secofs
• alaska
• !?

[pvelissariou1]

@saeed-moghimi-noaa ok, thanks. I'll see how to incorporate these in a best way. This is good !!!

[janahaddad]

notes from surge team tagup today:

• need to make the readme collaborative, maybe in google doc as Ufuk suggested.
• need to include how future requests are handled

[pvelissariou1]

I created a google doc shared with the team.
The doc is not ready for reviewing (basically a copy of the CoastalApp README.md). I am working towards the first draft. Feel free to add comments/suggestions so I can incorporate them into the draft.
The idea here is to have a general README file for ufs-coastal with basic background information, minimal usage information, references, etc. Don't forget that a full documentation will be developed for UFS-Coastal as well.

[dpsnowden]

I spoke to @saeed-moghimi-noaa yesterday and had some documentation questions. He referred me to this project. First, great job being so clear and transparent with the project goals and tasks! You're providing a wonderful example for us all!

I'm glad the README is progressing and look forward to reviewing it. Hopefully my question is appropriate to ask here, if not, let me know and I'll create a new ticket.

My question is about nomenclature and how we can be consistent throughout our docs and at all levels of the organization. Specifically, I'm struggling with the difference between Systems and Applications. I think the hierarchy that is emergins is something like:

• ufs-coastal is a System comprised of multiple components that come from other places in the community (e.g. SCHISM, FV3, ROMS etc).
• ROMS, SCHISM, etc are Component Models and we use certain versions of them in ufs-coastal.
• There are other elements of ufs-coastal beyond the component models (workflow, nuopc caps, data assimilation, etc.)
• We create Applications based on ufs-coastal by selecting certain components from the System and tailor them to specific needs (surge modeling, ecosystem forecasts, etc.)

I see two problems in our communications:

• We colloquially use the word "model" to refer to everything (e.g ROMS is a model, STOFS is a model)
• The UFS nomenclature refers to UFS Apps e.g. coastal app, weather app, hurricane app etc. But that should really be coastal system, weather system, shouldn't it? (I recognize that introduces challenges too.)
  Here's a diagram that captures my thinking, it's not perfect, I'm mostly using it here to differentiate between SYSTEM and APPLICATION. Maybe we need another word.

I think it's important to establish some common vocabulary as we're coordinating this enormous project and trying to communicate between developers, managers, external PIs and even NOAA leadership. Thanks for your thoughts.

[pvelissariou1]

@dpsnowden Derick, thank you for your comments. Yes language is very important. Let me finalize the README draft and then we will iterate to finalize the document. The same goes for the license file for UFS-Coastal.
Both files are important for ufs-coastal.

[janahaddad]

@dpsnowden I'm not one to underestimate the power of communication, so I can definitely see this is important to get right in the ReadMe and elsewhere

My understanding from the (relatively short) time I've been on this project, is that -- based on the nomenclature the UFS-Coastal team uses -- there are multiple "component" types, one of which is the model component:

• model component: includes ADCIRC, FVCOM, ROMS, SCHISM on top of what's already available in UFS-Weather Model
• data component (CDEPS): these are various data forcings that kind of act as stand-ins for an active model, with any spatial/temporal interpolation taken care of by the NUOPC cap.
• mediator component (CMEPS): manages the way that model and data components interact
• driver component: allows for adding new components to a particular coupling configuration. One of the eventual goals of this project is to transition to the ESMX driver

The various coupling "applications" are also called "configurations" within ESMF documentation and elsewhere (including the way we talk about it internally). So maybe in that sense, if those two terms were better differentiated as coastal app, weather app, etc. & SCHISM+WW3 configuration, DATM+ROMS+CICE configuration, etc. ... then perhaps that helps solves the problem?

@uturuncoglu @pvelissariou1 @saeed-moghimi-noaa please correct & apologies if I have misrepresented anything above

[dpsnowden]

Thanks, @janahaddad. It sounds like "applications" and "configurations" can be used interchangeably. I'll probably opt for "applications" in presentations because it feels a little more approachable and plain language for non-modelers. Since those seem distinct, I'll separate mediators and drivers in my figure (and presentations). I've been lumping them into a general "infrastructure code" category, but I don't see any harm in being specific. But this brings up another question that's separate from the vocabulary issue. What's the difference, or intended difference, between the ufs-coastal repo and the ufs-coastal-app repo? Those should be clear in the README's and in all the Sphinx docs too. I understand that there is some .gitignore wizardy that has to happen before we can make the repo's reflect the answer. But, in principle what's the difference? It doesn't seem to me that the ufs-coastal-app repo is an Application in the way we've been defining it here.

On another note, the reason I'm digging into nomenclature so much is that I'm trying to document the full plan for:

1. making our modeling infrastructure UFS compliant. Said another way, developing the ufs-coastal "system" and
2. migrating existing operational applications from their current configuration into the ufs-coastal system infrastructure.

I don't know if this repo is the right place (hopefully?) to document the roadmap but that's my hope. If I'm right, shouldn't "Transition to ESMX" be a phase/milestone/iteration on this roadmap?

Last question, that I'll pose in another issue.... Is data assimilation part of the ufs-coastal? Or is JEDI sufficiently distinct that it should be addressed elsewhere?

[pvelissariou1]

@dpsnowden At this stage data assimilation is not part of ufs-coastal. I have completed the firts draft of the README file that contains brief instructions for the compilation of UFS-Coastal. The file is currently shared with @saeed-moghimi-noaa , @janahaddad , @gseroka , @dpsnowden , @SorooshMani-NOAA , @BahramKhazaei-NOAA , @FariborzDaneshvar-NOAA , @[email protected], @uturuncoglu and @yunfangsun . Please take a look at the file and post (comments) any suggestions you might have.

[pvelissariou1]

@dpsnowden , @saeed-moghimi-noaa , @janahaddad We might need to insert a disclaimer section at the end of the document. Also after the first round of reviews, we may start working on the wording of the document.

[pvelissariou1]

04/03/2024 update

• Storm surge team has suggestions that will be incorporated into the document on 04/04/2024 (mostly technical and clarfications)
• Disclaimer will be added as well

Finalize the draft by Monday 04/08 for further review

[saeed-moghimi-noaa]

@pvelissariou1 and the team,
Thanks for the hard work on this. @janahaddad as discussed yesterday in Agile meeting with EPIC , we will continue the conversation with NOS leadership and EPIC in terms of where ufs-coastal and its applications will stand in comparison with ufs-weather-model and its applications. To stay consistence it may make sense that we rename ufs-coastal to ufs-coastal-model .

[dpsnowden]

I'm done reviewing the document. Great work and thanks for the opportunity to weigh in.

[janahaddad]

Closing this ticket and will open another to start moving readme, Wiki, etc. to coastal-app repo instead, per our recent discussions in the team and with @dpsnowden