Climatemachine.jl: Flatten directory structure

[jkozdon]

I have been wondering if we want to further flatten the directory structure and use the convention the directory names and module names. Further we may want to use CamelCase for directory names since this matches the Julia module naming convention.

For instance

• Planet-parameters would become PlanetParameters
• CLIMA-atmos/Dycore would become CLIMAAtmosDycore

This seems to be more inline with what some other Julia projects are doing and it simplifies finding where a module is defined.

/cc @lcw @tapios @vchuravy @peterahrens @charleskawczynski

[tapios]

I'm in favor of flattening. CamelCase generally is also fine with me. But constructs such as CLIMAAtmosDycore are hard to read. Underscores or hyphens would help here.

[christophernhill]

Could/should we skip CLIMA in CLIMAAtmosDycore?
Its already in the CLIMA repo, so we could just do AtmosDycore - maybe?

Chris

On Wed, Dec 19, 2018 at 7:47 PM Tapio Schneider
[e-mail] wrote:
>

I'm in favor of flattening. CamelCase generally is also fine with me. But constructs such as CLIMAAtmosDycore are hard to read. Underscores or hyphens would help here.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[glwagner]

Even just Atmos might be sufficiently descriptive and memorable.

[tapios]

@jkozdon Some more thoughts on this:

1) Directory hierarchy is useful where it reflects logical hierarchy. I propose we leave, e.g., Atmos/Dycore, Atmos/Parameterizations etc. Otherwise the root where Atmos lives will get very unwieldy soon (many model components, each with their own hierarchy...)

2) If we want to use Camel Case for directories, let's omit the CLIMA in front of Atmos etc.

3) Camel Case for modules and structs is also fine, for consistency with Julia.

4) But underscores in function and variable names increase readability, and I favor retaining those.

[charleskawczynski]

This all sounds good to me. Maybe we can move the coding conventions document into CLIMA somewhere and update it using these ideas?

[jkozdon]

re: @tapios

I suppose my default recommendation is that we start with the Julia style guide recommendations, and then specify deviations from that.

1. Within Julia we can create submodules as well. So the unwieldiness could be managed there, if it made sense to one have a few core modules, say AtmosDycore andAtmosParameterizations
2. Sounds good to me
3. Sounds good
4. This is the Julia style guide as well.

From [style-guide]:(https://docs.julialang.org/en/v1/manual/style-guide/index.html#Use-naming-conventions-consistent-with-Julia-base/-1)

• modules and type names use capitalization and camel case: module SparseArrays, struct UnitRange.
• functions are lowercase (maximum, convert) and, when readable, with multiple words squashed together (isequal, haskey). When necessary, use underscores as word separators. Underscores are also used to indicate a combination of concepts (remotecall_fetch as a more efficient implementation of fetch(remotecall(...))) or as modifiers.
• conciseness is valued, but avoid abbreviation (indexin rather than indxin) as it becomes difficult to remember whether and how particular words are abbreviated.

[tapios]

Thanks, @jkozdon. Following Julia style where it makes sense sounds good to me. Regarding directory structure, while I am in favor of flattening unnecessary hierarchy, I am not convinced we should flatten so much as to put AtmosDycore and Atmos etc. into one root. Several reasons:

1. Our code will be complex in the end, more comparable, say, to an OS kernel than to most Julia projects. Some structure will help (as it does, say, in the Linux kernel).

2. With the proposed convention, we would end up with complicated constructs such as AtmosParameterizationsRadiationRRTMG. I would find it helpful to have directory structure for it, rather than loading the names with the structure.

3. We will need some code in other languages, e.g., for radiation. Again, easier to drop it into a directory for radiation..

4. The atmosphere, ocean, land etc. models should work as standalone models in the end. It's easier to identify what one needs for these models if there is a directory tree for each of them, and directory trees for shared code.

That being said, I'm not sure we need hierarchies like Parameterizations/src (but if there is a good reason for having that, I can be convinced otherwise).

[jkozdon]

I suppose the bigger issue than directory structure, is packages vs modules vs files.

Packages have to have the own src/ directory as well as a Project.toml and (most of the time) Manifest.toml. We can have modules within packages too, but these need not have their own src/ directory.

Naively, it seems to me that pieces we imagine being spun off at standalone components should be packages, and these need to be uniquely named.

One option would be that Atmos is a package, with Dycore, Parameterizations, etc. as a submodule. To use these you would then type using Atmos.Dycore or using Atmos.Parameterization in the code.

Another option would be the AtmosDycore and AtmosParameterization are the packages, with possible submodules.

Packages we can version, whereas modules we cannot.

We also have the possibility of just dropping everything in files and using the include mechanism everywhere, but this will cause problems with the namespace.

[tapios]

@jkozdon All good points. I think you guys can make this structural decision, given that we need a standalone atmosphere model (both in global and LES configurations, which may differ slightly in terms of SGS models), and other standalone models. We will also want to use, e.g, various parameterizations in offline (single-column) mode, but I suppose that can be done whether they are packages or modules.