poly_a and poly_b vs PolynomB and PolynomA in documentation

[TeresiaOlsson]

I'm wondering about poly_a and poly_b in the documentation. For some of the lattice elements it says:

poly_a – Array of normal multipole components
poly_b – Array of skew multipole components

and then

PolynomB – straight multipoles
PolynomA – skew multipoles

So poly_a sets PolynomB and poly_b PolynomA? Or is the documentation wrong?

[lfarv]

Hi @TeresiaOlsson,

So poly_a sets PolynomB and poly_b PolynomA? Or is the documentation wrong?

Are you referring to the documentation of at.Multipole? If so, you are right: poly_a and poly_b are positional arguments, you can give them the name you like, it does not matter, and they do set the PolynomA/B attributes. Here they have been named according to the usual PEP rule: lower case and undescores to separate words. But we could change the name an any time without breaking anything.

What matters is the name of keyword arguments (as in at.Quadrupole, for instance), and of course element attributes. There, the names are PolynomA and PolynomB and cannot be changed. In element constructors, the rule is that the keyword corresponds exactly to the attribute name.

Conclusion: nothing wrong and your statement is right. We could change the names of positional arguments of at.Multipole to PolynomA/B, it would just cost a warning in some IDEs: Variable in function should be lowercase

[TeresiaOlsson]

Yes, and at.Dipole. I'm not sure I still understand.

My confusion is about which one is the normal and which one is the skew. According to what the documentation says at the moment PolynomB is the normal multipoles, but for the positional arguments it's poly_a which is the normal multipoles. That doesn't seem correct to me?

Especially not when the code seems to do this:
poly_a, len_a, ord_a = getpol(_array(kwargs.pop('PolynomA', poly_a)))
poly_b, len_b, ord_b = getpol(_array(kwargs.pop('PolynomB', poly_b)))

I think the documentation should be changed from:

poly_a – Array of normal multipole components
poly_b – Array of skew multipole components

to

poly_a – Array of skew multipole components
poly_b – Array of normal multipole components

[lfarv]

@TeresiaOlsson : sorry, I misunderstood your message. Now I see the problem, and you are right, there is a documentation problem. I'll open a pull request to fix that. Thanks!