Parser: "singular" methods are obsolete and should go

[rpoyner-tri]

The "singular" methods are deeply awkward to implement for multi-model capable formats, and perhaps have outlived their usefulness with the ability to scope-name models rather than renaming them. Consider deprecation and removal.

See discussions in #17623.

[rpoyner-tri]

We should do #18060 before deprecating the singular methods.

[rpoyner-tri]

Partially addressed in #18110.

[rpoyner-tri]

Draft/prototype is at #18157. That needs to become a PR train and get some further design review. #18266 tries to dispose of some of the boring parts. More to come.

[rpoyner-tri]

More boring parts swept into #18277.

[rpoyner-tri]

Adding a concern here, first discovered in #18878. The dmd.yaml format doesn't currently have a multi-model aware file loading statement. If we hope to wipe out the singular methods entirely, dmd.yaml will need some changes (add_models statement?, options for prefixes, auto-renaming, etc.). Also, places in other code where dmd.yaml has been used to retain forced model renaming would have to be reviewed and possibly rewritten.

[jwnimmer-tri]

My hypothesis is that we could have the add_model: yaml syntax call AddModels plural. I think all API promises would still hold, and it would not generate any implementation complexity. The default_joint_positions could either apply to only the first model, or we could search all of the added models.

[rpoyner-tri]

At the very least, the name field would have to be deprecated. The entire point of this odyssey was to move away from whack-a-mole model renaming.

[jwnimmer-tri]

Yes, we should look at deprecating name, but it's also simple to make an improvement here without doing that, if we decided it was a good trade-off:

• if name is not given (or empty), use the plural parser;
• if name is given, use the singular parser.

Maybe that is too confusing, and we need to create struct AddModels (with an "s") for the dmd schema? I imagined that would be a lot of pasta though, for little benefit.

Making the name optional seemed to me like it might be the smoothest ramp towards removing the renaming entirely. Possibly this deserves some prototyping versus Anzu, to see what ends up working best.

[EricCousineau-TRI]

Minor concern about removing //add_model/@name is that it forces users to use names like carrot_1, carrot_2 (numbering) or left::carrot, right::carrot (scoping). It may preclude users from using model names as an abstraction, e.g. I can swap in a Panda model or an IIWA model and just call it arm.

It additionally provides a divide in (simple?) composition functionality between model directives and SDFormat.

However, if we think scoping gives users the ability to be explicit about their purpose, and if we force users to shove abstraction further up the stack, I guess that's OK, esp. if we don't have concrete examples of above abstraction. Additionally, users can use SDFormat if they truly want that ability.

[calderpg-tri]

Minor concern about removing //add_model/@name is that it forces users to use names like carrot_1, carrot_2 (numbering) or left::carrot, right::carrot (scoping). It may preclude users from using model names as an abstraction, e.g. I can swap in a Panda model or an IIWA model and just call it arm.

I don't think this is just a minor concern. Loosing renaming just makes every existing case we have of multiple copies of the same model worse in terms of naming effort/clarity.

[jwnimmer-tri]

Any proposal to deprecate/remove the dmd name field would be contingent on prototyping the change vs Anzu to see how little (or much) it disturbs things. That would provide empirical evidence for whether the change is positive.

[calderpg-tri]

I don't think we need to prototype dmd changes in Anzu to see that loosing renaming has negative consequences. 10245 is enough evidence already.

[rpoyner-tri]

Closed by #19978.