Should we unify on a naming convention for the auto-used modules?

[bradcray]

Currently our auto-used modules are named:

• AutoMath
• Errors
• ChapelIO (referred to as "IO Support" in the docs)
• Types

This issue asks whether we should unify on some sort of naming convention for these modules, like Auto* or otherwise?

Some notes:

• The ChapelIO name is a bit weird since Chapel as a module name prefix is most often used to distinguish an internal module.

• For AutoMath and ChapelIO, the fact that they're not simply 'Math' and 'IO' lets us distinguish between features in those areas that are auto-available vs. those that are obtained through the standard 'Math' and 'IO' modules. However, it'd be nice to unify on a single prefix between the two.

  • Might we want standard modules with the names 'Errors' and 'Types' in the future, such that the auto-versions of these modules should get a similar prefix?

• We should stop renaming the ChapelIO module in the list of standard modules as well, so that if someone needs to refer to it in their code, they're able to do that (I'm not sure where/how that is happening...)

[lydia-duncan]

iirc, when we decided on the name AutoMath, we were intending that the other modules would follow suit. I think we just haven't implemented that yet (but haven't gone looking in the notes for that decision yet)

[bradcray]

That's been my assumption as well, but I didn't remember for sure (nor how firm the decision was), and think of it every so often (whenever I need to refer to one of them), so wanted to make sure we had an issue for it.

[mppf]

I'm for renaming ChapelIO somehow. I don't think I was involved in the discussion for AutoMath but I'd consider BuiltinMath as an alternative. For some reason, BuiltinIO feels better to me than AutoIO. AutoIO sounds like some kind of macro-based I/O generator or something (as in "It automates your IO!").

I'm not so sure that it's worth renaming Errors or Types at all. These don't have the quality of being a module split into available-by-default parts and not-available-by-default parts. To me, it seems OK for them to exist as modules with a good and simple name that happen to be use'd by default.

Another idea is to make these automatically included things all submodules of ChapelStandard. Then we could have ChapelStandard.IO as a different module from IO even though they have the same name. I like that in some ways but I'm also worried it has potential to cause confusion.

[bradcray]

I'm not so sure that it's worth renaming Errors or Types at all. These don't have the quality of being a module split into available-by-default parts and not-available-by-default parts. To me, it seems OK for them to exist as modules with a good and simple name that happen to be use'd by default.

But maybe we'd wish for standard modules with these names for more extensive features relating to types and errors in the future?

Another idea is to make these automatically included things all submodules of ChapelStandard. Then we could have ChapelStandard.IO as a different module from IO even though they have the same name. I like that in some ways but I'm also worried it has potential to cause confusion.

That's an intriguing idea, though I wouldn't use ChapelStandard as the parent module. Instead, I'd create a new, otherwise empty module like Auto, AutoUse, Builtins, or the like.

[lydia-duncan]

Looks like the discussion of that was here: #18989

Checking email, this issue was sent out to the whole team as part of the prep for the first review of the module and was presented for discussion in that meeting. The discussion of it in the meeting notes did not seem controversial, though the number of votes in the issue itself is pretty low.

In that issue, we also brought up not renaming Errors and Types, so I think it's fair to only focus on how ChapelIO needs to be renamed.

• We should stop renaming the ChapelIO module in the list of standard modules as well, so that if someone needs to refer to it in their code, they're able to do that (I'm not sure where/how that is happening...)

The rename in ChapelStandard is solely so that the module name is available to use with explicit naming of symbols in it. If we rename the module, I would expect/require us to update the as clause as well.

I'm not a fan of Builtins as a name, personally.

[mppf]

The rename in ChapelStandard is solely so that the module name is available to use with explicit naming of symbols in it. If we rename the module, I would expect/require us to update the as clause as well.

AFAIK Brad was talking about the documentation where the module is called "IO Support" -- see https://chapel-lang.org/docs/modules/standard.html#automatic-modules

[lydia-duncan]

That doesn't impact whether users can use ChapelIO to explicitly name symbols in it, and the module page for it lists that name. That display is handled by https://github.com/chapel-lang/chapel/blob/main/doc/rst/meta/modules/standard.rst?plain=1#L21 specifically

[bradcray]

@lydia-duncan : Just to make sure I'm understanding, you're not proposing that it's desirable for the standard module index to continue renaming it in this way, are you?

[lydia-duncan]

Well, I like it better than displaying ChapelIO in that page. If you're at the summary page trying to figure out where to look for default IO symbols, I think it accomplishes the purpose nicely. If you're at the summary page trying to figure out where ChapelIO is defined, it's less useful, but arguably a reader is more likely to have done a search for the name than to go to the summary page.

I don't have a problem removing that rename when we change the module name, though, and probably would lean towards doing so.

[bradcray]

I'm fine waiting until we rename the module, assuming we will. But if we didn't, it seems odd to me that it's the only entry on that table of contents page that doesn't include the name—particularly since you've pointed out that the name isn't secret or hidden once someone actually clicks on the link. If we're worried about module names not being sufficiently self-explanatory, I'd rather add a note after the entry like "automatically included IO features" than to have it be a singleton outlier like this. And I think arguably if we weren't doing the renaming, we might have renamed it long before now since it'd be more blatantly in our faces on this page.

[lydia-duncan]

Prep for the upcoming ad-hoc subteam

1. What is the API being presented?

These are the modules names for two modules included by default in user programs:

• ChapelIO
• AutoMath

They are both brought into the user namespace via a use statement in ChapelStandard.

The problems today are: we don’t like ChapelIO as a name, and it would be ideal for the two to share a common prefix, given that the prefix is intended for the same function (indicating that they are included by default)

How is it intended to be used?

The module name has two uses: to distinguish symbols within it from other symbols that share the same name (e.g. AutoMath.round()) and as the title of the generated documentation page for the module (e.g. https://chapel-lang.org/docs/latest/modules/standard/ChapelIO.html)

How is it being used in Arkouda and CHAMPS?

In Arkouda:

• ChapelIO is not used
• AutoMath is used 11 times:
  • in src/MsgProcessing.chpl 4 times
    • to distinguish AutoMath.round from other instances of round
    • https://github.com/Bears-R-Us/arkouda/blob/d00e2ffaffdad61165265310fd85f6596a51a62c/src/MsgProcessing.chpl#L168
  • in src/ServerConfig.chpl 3 times
    • to distinguish AutoMath.round from other instances of round
    • https://github.com/Bears-R-Us/arkouda/blob/d00e2ffaffdad61165265310fd85f6596a51a62c/src/ServerConfig.chpl#L298
  • in src/MemoryMgmt.chpl 1 time
    • to distinguish AutoMath.round from other instances of round
    • https://github.com/Bears-R-Us/arkouda/blob/d00e2ffaffdad61165265310fd85f6596a51a62c/src/MemoryMgmt.chpl#L122
  • in src/CommAggregation.chpl 3 times
    • to distinguish AutoMath.abs from other instances of abs
    • https://github.com/Bears-R-Us/arkouda/blob/d00e2ffaffdad61165265310fd85f6596a51a62c/src/CommAggregation.chpl#L416

In CHAMPS:

• ChapelIO is not used
• AutoMath is used 17 times
  • Most of these uses are of symbols that have been deprecated in AutoMath in favor of living in the Math module. The only exception is the use with ceil
  • in geo/geo.chpl 1 time
    • to distinguish AutoMath.ceil from other instances of ceil
  • in geo/src/computeGeoQuantities.chpl 1 time
    • to distinguish AutoMath.pi from other instances of pi
  • in meshTool/meshDeformation.chpl 1 time
    • to distinguish AutoMath.pi from other instances of pi
  • in common/src/computationalDomain.chpl 2 times
    • to distinguish AutoMath.pi from other instances of pi
  • in drop/src/dropInputs.chpl 2 times
    • to distinguish AutoMath.pi from other instances of pi
  • in flow/flow.chpl 1 time
    • to distinguish AutoMath.pi from other instances of pi
  • in flow/src/flowSolutionIO.chpl 5 times
    • to distinguish AutoMath.pi from other instances of pi
  • in flow/src/flowInputs.chpl 4 times
    • to distinguish AutoMath.pi from other instances of pi

2. What's the history of the feature, if it already exists?

ChapelIO as a module has been around since 2005, and was originally named _chpl_file. In 2007, it was renamed to _IO, and then to ChapelIO, a name it has kept ever since.

For context, the IO module was created in 2011, partially taking symbols out of ChapelIO (though a significant amount still remained) and partially introducing a significant amount of new functionality. Over time the amount of symbols defined in ChapelIO would be reduced to the current ones it contains today.

AutoMath was recently split from Math.chpl so that some of the symbols defined in Math.chpl would require use or import statements to be accessed while some could continue being included in all programs by default. The name AutoMath was chosen for the default included module to preserve the shorter name (Math) for what users would more commonly write. At the time, the intention was for the result of the decision to also apply to ChapelIO, but it wasn’t clear if that decision was binding (hence this discussion).

Prior to that split, the module was originally named sin_pi when it was added in 2006, then renamed to _chpl_math and then to Math later that year. There were some side functions defined in a module called UtilMath that were merged into it when we started documenting our standard modules. 


3. What's the precedent in other languages, if they support it?

a. Python

In looking at what is provided in Python by default, I see one module that is defined but also used automatically: the site module (https://docs.python.org/3.11/library/site.html#module-site).

Other symbols that are included by default are also available for explicit naming if you import builtins (https://docs.python.org/3.11/library/builtins.html), which is used to enable overriding a symbol that is included by default. So far as I can tell, there are no submodules within this to otherwise distinguish between symbols that are provided by default, and no alternate modules that fulfill the same purpose.

b. C/C++

C functionality requires a specific header to access. There are some headers that are referred to as part of the C standard library (wikipedia claims there are 29 at the time of this writing). Some of those have a std prefix in their name (e.g. stdbool.h, stdint.h, stdio.h), some do not (e.g. math.h, complex.h).

C++ in addition to headers relies on namespaces, where most of the headers in the standard library extend the std namespace or nested namespaces within it. The headers it provides as part of its normal standard library for the most part don’t have a common prefix, though there are still some with std at the front (<stdexcept>, <stdfloat>). It also includes many of the C headers, all with a c prefix before their name.

Because symbols aren’t included by default to begin with, there’s few to no instances of a name and a std prefixed name that I could find (C++ has <stdfloat> and <cfloat> but that’s about it).

c. Rust

Like C, Rust’s Standard Library is available in all programs but requires use statements to access symbols within it, e.g. use std::env. Amongst those modules, the only common prefixes I see are for differently sized versions of the same type (e.g. u8, u16 for unsigned integers).

d. Swift

Swift’s standard libraries are automatically imported by default. So far as I can tell from their documentation, there does not seem to be a module name used to distinguish where any of the default symbols are defined.

e. Julia

Julia has modules Core and Base to define things that are included in programs by default, and Base has a number of submodules. There are also separately a number of standard libraries that are available for using or import. I did not see a shared prefix amongst any of the modules, and there did not seem to be a module that was explicitly in both Base and the standard libraries with a similar name.

f. Go

Go has a number of symbols that it includes by default. Their documentation lists them in a “builtin” package but specifies that they are not actually in a package named builtin. The number of symbols listed there is on the smaller side and there don’t seem to be visible submodules under it. None of the standard libraries seem to have a prefix associated with them either.


4. Are there known Github issues with the feature?


Issues with the module name or concept of the automatic module:

• should it be possible to explicitly use/import the automatic modules? #19313 (should it be possible to explicitly use/import the automatic modules)
• Closed:
  • Math module: should we split it in two, one of which is not included by default? If so, what names should be used? #18989 (where the discussion of the naming for Math/AutoMath occurred)
  • proposal: do not include IO module by default but enable writeln #13448 (where we discussed stopping including IO by default in addition to ChapelIO)

Issues with the contents of the module:

• adjusting uses of int(?w) etc in the standard library #22814 (adjusting uses of int(?w) in the standard library)
• Different behavior between mod and fmod on real arrays with large real scalars #22584 (difference between mod and fmod)
• Generic **gcd** #20983 (request for gcd returning more specific integers)
• Should the library provide cast from user records to string?  #19893 (cast from user records to string)
• Should channel-less read*() routines be available by default? #19131 (question about if read* should be included in ChapelIO instead of IO)
• Could compiler-generated methods like readThis, writeThis, hash be implemented in module code? #19101 (question about if we can define readThis/writeThis in module code, where they would probably end up in ChapelIO)
• write and writeln does not support type argument #16917 (desire to support type arguments for write/writeln)
• What should the return type of log2 be? #10292 (what should the return type of log2 be)
• clean up documentation after 'out error' deprecation #9778 (documentation clean up request)

5. Are there features it is related to? What impact would changing or adding this feature have on those other features?

ChapelIO is related to the IO module and AutoMath is related to the Math module. I wouldn’t expect changing the names of these modules to impact their names.

Errors and Types modules are both also standard modules that are included by default (but we like their names and wouldn’t want to make them longer to match these two).

I don’t think we anticipate including more standard modules by default.


6. How do you propose to solve the problem?

A. use the prefix Auto (AutoIO, AutoMath)

• Pros:
  • Less churn for users
    • We already use it for AutoMath and AutoMath is more frequently named than ChapelIO
  • Relatively short
  • Closer to implying the difference between it and its prefix-less counterpart than many other options here
• Cons:
  • Maybe implies more action is being taken

B. use the prefix Std (StdIO, StdMath)

• Pros:
  • short
• Cons:
  • Both StdIO and IO live in the Standard Module documentation header and in the standard directory. So it’s not necessarily clear why one would have Std and the other wouldn’t

C. use the prefix _ (_IO, _Math)

• Pros:
  • Short
• Cons:
  • Not really clear what _ is trying to imply without learning more about the modules and looking for commonalities between them or differences between the _ version and its _-less counterpart.

D. use the prefix Builtin (BuiltinIO, BuiltinMath)

• Pros:
  • Makes it obvious why there are two modules with [ IO | Math ] in their name
• Cons:
  • Kinda long (but using them should be relatively rare)

E. use the prefix Util (UtilIO, UtilMath)

• Pros:
  • Relatively short
• Cons:
  • The “L” in Util and the “i” in IO are basically indistinguishable in certain fonts
  • Not really clear what Util implies about the contents

F. make them submodules of ChapelStandard or a new module, theoretically allowing them to have the same name as their top level counterpart

• Pros:
  • Less name wrangling - only have to figure out a full module name we like, rather than having to worry about what looks good next to IO
    • This would make Util slightly more viable
• Cons:
  • I’m skeptical this will actually allow them to have the same name as their top-level counterparts. I think they’ll conflict (especially because the submodule will be included by default) and I’m not sure of a good way to specify that a user wants the top-level module (which will be the more common case).

G. Some other name or idea?

I don’t view Chpl or Chapel as viable options so won’t even list them here.

My preference is for Auto