search

precice / fenics-adapter

preCICE-adapter for the open source computing platform FEniCS
GNU Lesser General Public License v3.0
27 stars 13 forks source link

Naming of software, package and repository #85

Closed BenjaminRodenberg closed 3 years ago

BenjaminRodenberg commented 3 years ago

We want to use the following names for this project:

This comes with a few todos:

MakisH commented 3 years ago

I see a trend towards "solver-preCICE Adapter" names lately. Just in case this did not already pop up and to document why our adapters are currently named as e.g. "OpenFOAM adapter for preCICE":

I understand that in the case of FEniCS this is maybe a bit less natural, as we also write the solver. But then I am not sure I understand the "-preCICE" part. I guess the problem lies in the "adapter" part of the term in this case, where "example" could be more descriptive (but probably also incomplete).

Also, small question: what is the motivation behind the uppercase "A" in "Adapter"? We currently don't use this form anywhere else.

BenjaminRodenberg commented 3 years ago

@MakisH Thanks for the input!

We came across this issue while writing the paper for the FEniCS(-preCICE) adapter. When thinking about the title we revisited the actual name of the software. Currently we are only writing "FEniCS Adapter". However, this does not really tell a lot about what the adapter is actually doing from the perspective of somebody who is not from within the "preCICE bubble". Therefore, we decided to extend the name of the software to "FEniCS-preCICE Adapter".

The "-preCICE" part represents (from my point of view) the for preCICE in "FEniCS adapter for preCICE".

Regarding the small question: I think the uppercase "A" currently has no real reason. "FEniCS-preCICE adapter" is also fine.

BenjaminRodenberg commented 3 years ago

@uekerman @IshaanDesai: We did not really discuss the name "FEniCS adapter for preCICE" yet. Did we?

MakisH commented 3 years ago

If the issue is people understanding what this is about, then:

uekerman commented 3 years ago

I think it's time to properly discuss this :grin: I also had it on the agenda for Wednesday.

Historically, we used all kinds of different names :see_no_evil:

The adapter adapts OpenFOAM, not preCICE, so OpenFOAM adapter. The adapter does everything to make OpenFOAM compatible with preCICE, so for preCICE. One could also say of preCICE (part of the "ecosystem").

I guess those points you could also turn around. I think it's just our preCICE viewpoint. "The adapter adapts preCICE to be usable by OpenFOAM. The adapter does everything to make preCICE compatible with OpenFOAM". That could be the perspective of an OpenFOAM user hearing the first time about preCICE and its adapter, right?

"Solver-preCICE adapter" would be a symmetric name, suggestion by @ajaust. An adapter between the solver and preCICE. Adapting both ways.

Also, small question: what is the motivation behind the uppercase "A" in "Adapter"? We currently don't use this form anywhere else.

Motivation was to make it a proper name.

MakisH commented 3 years ago

I guess those points you could also turn around. I think it's just our preCICE viewpoint.

I think that from a software perspective it is clear: an adapter modifies the solver code, which needs to be recompiled (or directly the runtime execution steps). preCICE itself does not even know that this ever happened.

Note that here I assume "adapter = someone that adapts something". Not generically something that goes in between and converts "stuff" from A to B and B to A (unclear what "stuff" is + this is what preCICE is mainly doing).

"The adapter adapts preCICE to be usable by OpenFOAM. The adapter does everything to make preCICE compatible with OpenFOAM". That could be the perspective of an OpenFOAM user hearing the first time about preCICE and its adapter, right?

This sounds wrong to me, due to the "preCICE (code) is not being modified" argument.

"Solver-preCICE adapter" would be a symmetric name, suggestion by @ajaust. An adapter between the solver and preCICE. Adapting both ways.

What is it adapting?

Motivation was to make it a proper name.

I am not sure if this will help solve some problem or if we will end up with both forms being used interchangeably.

uekerman commented 3 years ago

Note that here I assume "adapter = someone that adapts something". Not generically something that goes in between and converts "stuff" from A to B and B to A (unclear what "stuff" is + this is what preCICE is mainly doing).

Maybe that's the important point. For me, adapter was always the thing in between. Sth like this. :smile: And "adapting" is what it does = converting data structures, converting coupling logic, etc.

Besides the best choice (if there is a best choice), I think it's time to come up with a consistent naming scheme.

In my opinion, it would be good to have a naming scheme that works for both the software name and the "code name" / "package name".

Paper title: "Software name: Coupling FEniCS to other Simulation Software"

import packagename

The repository names are good. Here, it is ok to take our viewpoint.

IshaanDesai commented 3 years ago

Taking into consideration what preCICE does, FEniCS adapter for preCICE does not seem correct to me, because we provide an adapter to couple FEniCS using preCICE and not for preCICE. Using for might confuse a new reader into thinking that preCICE is another solver. A long description would be "Adapter to coupling FEniCS using preCICE". My suggestions would be:

ajaust commented 3 years ago

I like the new name fenicsprecice for the package.

For now I would stick with the term "adapt/adapter". Who adapts what for who depends a lot on the software used, perspective taken etc. We could have a long discussion about that some other time/place. :-D

Nevertheless, i like the suggestion of @MakisH to drop the term "adapter" when suitable and just use the name of the package or something similar. That should avoid confusion. Thus, I also like @uekerman's new title suggestion.

As already mentioned I suggested something like "Solver-preCICE adapter" as consistent naming scheme that is somewhat vague what is actually adapted, but reflects the name of the solver it is intended to be used with and points to preCICE. I assumed that "pointing" to preCICE might be needed for users who would be completely new and just stumble over the paper or package description.

uekerman commented 3 years ago

Thanks for the opinions :+1: More are very welcome!

Quick remark: if possible we could avoid prepositions in the software's name. Makes it shorter and easier to recognize as a stand-alone name.

MakisH commented 3 years ago

For the software name (not a machine-readable name), I would then suggest something like: preCICE::FEniCS, preCICE::OpenFOAM, etc. (no strong feelings for the separator, maybe a simple - would be more versatile).

Since we need a "generally recognizable" software name, let's simply drop the "adapter" part there (and only there): it is anyway a term only we are using in this way and it is already confusing. I think both my view ("adapts the code") and @uekerman's view ("adapts data structures") have cases that don't perfectly fit.

@IshaanDesai:

Taking into consideration what preCICE does, FEniCS adapter for preCICE does not seem correct to me, because we provide an adapter to couple FEniCS using preCICE and not for preCICE.

Fair point, but I would argue that we change the verb in this sentence: couple X using Y vs adapt X for Y. I read it as prepare FEniCS for preCICE.

I agree with your repository and package name suggestions / argumentation.

Software name: preCICE Adapter for FEniCS. I would stress on the capital "A" as we are naming a software, it is the title.

This is mostly a style-related discussion. There are names with lowercase letters, for example "preCICE", "deal.II", etc. But indeed, not a very common pattern. Maybe a useful example for your approach would be "LibreOffice Writer", "LibreOffice Impress" etc.

Related curse in all this discussion: if we use "preCICE" first, it will often be automatically be converted to PreCICE.

BenjaminRodenberg commented 3 years ago

To give a quick summary/overview:

I have the impression that we have concluded on the two points (please "thumbdown" and comment, if you don't agree. "thumbup", if you agree)

The "software name" is still open. Here a quick summary of the suggestions (please comment, if I'm missing something):

Do we already have a conclusion on capitalization? I have the impression that we are slightly going into the direction of Adapter, since it is a name.

I have the impression that already what we have in mind with "software name" is a bit vague (at least in https://github.com/precice/fenics-adapter/issues/85#issuecomment-699970636 there are two different interpretations or usages). From my point of view we are looking for a software name that

  1. can be used as part of a paper title (https://github.com/precice/fenics-adapter/issues/85#issuecomment-700015941)
  2. can be used as a header for the README.md or title of the documentation (https://github.com/precice/openfoam-adapter)
  3. can be used inside the text of the paper to refer to the software

Do we look for a name that satisfies all three requirements at the same time? Or do we actually look for three different names for different purpose?

MakisH commented 3 years ago

I imagine the "software name" as something that could also be on a logo and I agree with the use cases.

No strong feelings for the "A/a", but I would prefer the term to not be there at all (see comment just before yours).

BenjaminRodenberg commented 3 years ago

After personal discussion with @uekerman, @MakisH, @atotoun, @KyleDavisSA and @fsimonis we have now a partial conclusion:

This gives us a shorter list of candidates:

Main question is now: Which separator (-, ::, ...) do we want to use? preCICE first or solver first?

This might also re-open the discussion about the package name (fenicsprecice): Calling the software preCICE::FEniCS, but the package fenicsprecice is confusing and inconsistent.

fsimonis commented 3 years ago

Further thoughts

Text examples

preCICE-OpenFOAM was developed as part of Gerasimos Chourdakis' master's thesis. It is based on previous work by Lucia Cheung (master's thesis in cooperation with SimScale).

preCICE::OpenFOAM was developed as part of Gerasimos Chourdakis' master's thesis. It is based on previous work by Lucia Cheung (master's thesis in cooperation with SimScale).

preCICE+OpenFOAM was developed as part of Gerasimos Chourdakis' master's thesis. It is based on previous work by Lucia Cheung (master's thesis in cooperation with SimScale).

preCICE/OpenFOAM was developed as part of Gerasimos Chourdakis' master's thesis. It is based on previous work by Lucia Cheung (master's thesis in cooperation with SimScale).

preCICE.OpenFOAM was developed as part of Gerasimos Chourdakis' master's thesis. It is based on previous work by Lucia Cheung (master's thesis in cooperation with SimScale).

My opinion

Based on this, my proposition is:

Where What
Adaptee FEniCS
Repository precice/fenics-adapter
Name in clear text preCICE/FEniCS
Package precice.fencis
uekerman commented 3 years ago

My subjective view:

MakisH commented 3 years ago

We could also use / as separator. This again would be consistent with the repository name.

I would expect this to have similar issues as :: (imagine / in a URL), even though I visually like both separators more than other options. I guess the only viable options are - and _.

Placing preCICE before the solver (e.g. preCICE/OpenFOAM) may be a bit too intrusive. The adapter is the smaller and less relevant part compared to the solver.

I prefer FEniCS-preCICE over preCICE-FEniCS, to frontload the important part. In the end, the adapter is mostly about the code we couple, not preCICE. But here, I don't have a strong opinion. I am OK with preCICE-FEniCS if more people prefer this.

I see that you both favor FEniCS-preCICE with these two contradicting arguments. I guess it feels more natural for most people and I also don't have such a strong preference apart from the reasons I explained above. I am also fine with FEniCS-preCICE (by coincidence it fits our ATHLET-preCICE)

I don't like any other separator than "minus/hyphen" so far as they are all not allowed punctuation in "normal" language.

I also agree that we should prefer - (or _), but let's please not say "minus" out loud. It will be super confusing. :see_no_evil:

MakisH commented 3 years ago

At the end of the day, and since everybody is now used to the "adapter" terminology, the originally suggested name "FEniCS-preCICE adapter" is actually not bad. We only need to agree to always mean "the thing that goes in between".

And we could also set that "FEniCS-preCICE adapter" (officially) == "FEniCS adapter" (in the preCICE context) == "the adapter" (in the FEniCS-preCICE context), wherever applicable. As an extension to this, a FEniCS user would probably always call it "the preCICE adapter". I guess this would be the most natural extension of what we already have, even if it maybe not how we could have (in retrospective) designed our language to be consistent across use cases.

MakisH commented 3 years ago

An additional thought in favor of the "FEniCS-preCICE" name:

$ sudo apt install fenics-precice
The following NEW packages will be installed:
   fenics libprecice2 pyprecice fenics-precice

In this hypothetical scenario, fenics-precice (or any solver-precice) is an extension to FEniCS, which uses preCICE. Therefore, it makes sense that the fenics part comes first.

BenjaminRodenberg commented 3 years ago

A short summary on the current state (borrowing table from https://github.com/precice/fenics-adapter/issues/85#issuecomment-701252555) follows below. I'm adding some results from https://github.com/precice/fenics-adapter/issues/85#issuecomment-702780569 and personal discussions from chat.

Where What
Adaptee FEniCS
Repository precice/fenics-adapter
(official) Name in clear text FEniCS-preCICE adapter
Name (in preCICE context) FEniCS adapter
Name (in FEniCS-preCICE context) the adapter
Package name fenicsprecice

On the package name

Generally we don't have strict rules for the package name, since this strongly depends on the used programming language, the community and corresponding conventions. Depending on the design of the adapter there might not even be a package, but only a class (Deal.II?) or something completely different is happening (SU2?).

Note: I do not really have a lot of experience with the Deal.II and SU2 adapters, therefore, the examples might be entirely wrong. If somebody with experience can verify the examples and edit this post that would be great :smile:

So why fenicsprecice?

Some more usage examples:

This is just a copy-paste from our chat in order to document which kind of ideas and use-cases generally exist (also outside of the python-FEniCS world):

MakisH commented 3 years ago

Since it looks like we need this, an overview of our current adapters:

On your usage examples:

ajaust commented 3 years ago

I agree with where the discussion is at the moment. The hyphen/minus might look boring, but it is "safe" to use as argued by @uekerman and I also like the that it would work nicely as package name in Ubuntu or other package managers as pointed out by @MakisH .