Update MOM6-examples tutorials?

[hdrake]

Is there any documentation of the example experiments aside from the few tutorials linked here: https://github.com/NOAA-GFDL/MOM6-examples/wiki/Tutorials#explanatory-jupyter-notebooks?

Are there any plans for more extensive documentation like there is for the MITgcm verification experiments https://mitgcm.readthedocs.io/en/latest/examples/examples.html?

I've started working through some of these experiments and exploring the output with Jupyter notebooks and xarray. Would it be helpful if I updated the existing tutorials, which still use clunkier scipy.io.netcdf objects, and added some more extensive documentation for some test/example experiments?

[kshedstrom]

I don't know of any plans to update those tutorials. I think it would be quite helpful for you to do what you can. If you can update to more modern Python, that's all to the good!

[JessCG]

@hdrake Yes please! I am hoping to eventually upload my idealized configuration which uses the same workflow as the global MOM6+SIS2+COBALT and is not very computationally expensive to run. I have lots of notebooks to generate simple grids, idealized input files, initialization files both from data products and spin ups, etc. I am mostly using netcdf4 because there are some formatting issues I could not track down with xarray's to_netcdf but perhaps you will succeed where I did not! :)

I was inspired by @ElizabethYankovsky's awesome documentation (https://github.com/NOAA-GFDL/MOM6-examples/tree/dev/gfdl/ocean_only/rotating_gravity_current). Have you seen it?

[markyoder]

How about just some updated syntax example, for example for the mkmf parts of the compile process? I'm pulling out my hair trying to figure out a syntax to make something like, mkmf -l '-L${FMS_PATH} -lfms' (as per: https://github.com/NOAA-GFDL/MOM6-examples/wiki/Getting-started ) work correctly (ie, adding -L${FMS_PATH} -lfms to the linking instruction in Makefile. This, and every syntax variation so far can correctly interpret -l L${FMS_PATH} correctly, but interprets the library link (-lfms ) as a mkmf -l, and so passes just fms to the linking instruction, etc.

Some working examples would be immeasurably helpful! Thanks in advance!

[marshallward]

@markyoder Is this a single-quote vs double-quote issue in the shell? Or something else? Regardless, it should not be a problem to provide more examples. If you could post your steps here and the error logs then we may be able to sort it out, and can develop an example from there.

[markyoder]

The linked example would suggest to pass multiple directives in single quotes, eg: mkmf -l '-L Path1 -la -LPath2 -lb' .
When I do that, I see quotes in my makefile and errors due to unrequited spaces.
I have something like,
${MKMF_DIR}/mkmf -t ${MKFM_SHERLOCK_TEMPLATE} -o '-I${BUILD_PATH_FMS}' -p MOM6 -l"-L${BUILD_PATH_FMS} -lfms" -c '-Duse_AM3_physics -D_USE_LEGACY_LAND_' path_names

But as I said, I cannot convince it to pass the entire linking instruction, "-L${BUILD_PATH_FMS} -lfms".

Instead it does some combination of interpreting the internal -l as an instruction to mkmf (and so just passing the string fms ) or throwing an error on the space separating the -L and -l flags.

I think, more than a question of how mkmf, not the shell, interprets single/double quotes -- or () or other grouping/delimiting characters.

[marshallward]

If I run your example:

BUILD_PATH_FMS=some/path
${MKMF_DIR}/mkmf \
  -t ${SOME_TEMPLATE} \
  -o '-I${BUILD_PATH_FMS}' \
  -p MOM6 \
  -l"-L${BUILD_PATH_FMS} -lfms" \
  -c '-Duse_AM3_physics -D_USE_LEGACY_LAND_' \
  path_names

Then the OTHERFLAGS in variable has -I${BUILD_PATH_FMS} (without substitution as in single quotes) and the MOM6: rule has the following (with substitution as in double quotes):

MOM6: $(OBJ)
    $(LD) $(OBJ) -o MOM6 -Lsome/path -lfms $(LDFLAGS)

I don't see any confusion about -l flags inside or outside strings.

Your other example using -l '-L Path1 -la -LPath2 -lb' gives a similar result:

MOM6: $(OBJ)
    $(LD) $(OBJ) -o MOM6 -L Path1 -la -L Path2 -lb $(LDFLAGS)

There could be some bad interactions due to the placement of the -l flags, perhaps based on the value of LDFLAGS. (Formally, the placement of these flags is a bit questionable, although AFAIK no one has ever reported an error).

However, I think we are getting a bit off track from the original proposal of constructing examples for the repository.
@markyoder If there is a genuine error in mkmf, would you mind submitting it to its project page?

https://github.com/NOAA-GFDL/mkmf

[markyoder]

Ok; I'll have a closer look. Come to think of it, I was referring to the error message I was getting, not directly to the Makefile, which would be consistent with the flag placement possibility. Honestly, I don't usually use those features of mkmf; I usually code those variables and flags into a compile script -- which is my current workaround. But I'll dig a little deeper to see if I can better clarify.
I suppose it could also be shell related (I'm on a CentOS7 BASH 4.2.46 shell)? In any case, thanks for the feedback.