Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define CommonSpaces module #2082

Merged
merged 1 commit into from
Nov 21, 2024
Merged

Define CommonSpaces module #2082

merged 1 commit into from
Nov 21, 2024

Conversation

charleskawczynski
Copy link
Member

This PR extends the CommonGrids module with the CommonSpaces module, allowing users to construct common spaces. These convenience constructos are a thin layer that simply forward to their convenience grid constructor counterparts and (if necessary) include an additional staggering keyword argument.

Copy link
Member

@Sbozzolo Sbozzolo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code looks great to me. (Please, add documentation, examples, and entry in the NEWS file)

@charleskawczynski charleskawczynski force-pushed the ck/CommonSpaces branch 2 times, most recently from f1ef935 to 3257f4b Compare November 12, 2024 02:00
@charleskawczynski
Copy link
Member Author

Code looks great to me. (Please, add documentation, examples, and entry in the NEWS file)

I did add documentation, but I'd like to figure out a way to minimize the duplicate documentation, since every argument is forwarded except for the staggering keyword argument.

For the examples, I added similar counterparts. I kind of wish we could automate this somehow.

Copy link
Member

@Sbozzolo Sbozzolo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still find the documentation insufficient, but we can iterate over.

Here's why I think that the documentation is insufficent. Thinking about different users:

As a new user

As a new user visiting this repo to learn more about how to set up a simulation, I click on "Docs". Nowhere on the left bar there's a mention of the computational domain. So, I click on "Examples". Nowhere in the page there's a mention about the computation domain. I am lost.

As a user with familiarity with the concept of Space but not the details

The only trace that convenience constructors for Spaces exist is a brief mention to News item. They are never used in any example. The docstring just mentions that they call some Grid constructor, but, having little familiarity with the internals, I don't know what Grids are and why I should care about them. The examples in the docstrings are trivial and don't tell me much. I have to dig to the test cases to find a place where I can learn more about these functions, but even there, the tests are just checking properties of the underlying Grid.

As scientist developing ClimaAtmos

I want to set up use these constructors to set up a Space. I read the docstring to learn about this feature. I've never really heard of Grids or used CommonGrids. I don't have any examples on how to use them, so I have to read the tests.

src/CommonSpaces/CommonSpaces.jl Outdated Show resolved Hide resolved
@charleskawczynski
Copy link
Member Author

Yeah, I'll apply the doc string changes and open an issue to tackle some of the bigger picture docs.

@charleskawczynski
Copy link
Member Author

I widened the scope of #2068, and updated the API docs, and applied a few doc fixes.

src/CommonSpaces/CommonSpaces.jl Outdated Show resolved Hide resolved
@charleskawczynski charleskawczynski merged commit a932c51 into main Nov 21, 2024
30 of 34 checks passed
@charleskawczynski charleskawczynski deleted the ck/CommonSpaces branch November 21, 2024 19:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants