[Open Discussion] New source attribute naming convention for 3.0

Currently in version 2.3.0b, source objects have their attribute names written out in full: Example from the magnet box source.

.magnetization
Magnetization vector of box in units of [mT].

.dimension
Magnet dimension=[a,b,c] which correspond to the three side lengths of the box in units

.position
Position of the center of the magnet in units of [mm].

.angle
Angle of orientation of the magnet in units of [deg].

.axis
Axis of orientation of the magnet.

The API for the constructor currently makes use of keywords such as mag, dim, pos, angle, axis to set the value for these attributes.

In the upcoming 3.0.0 release, it has been suggested to shorten all the attribute names to match the API. We’re also introducing a new relative position attribute regardless, which replaces both axis and angle. The current proposal for the attribute names is as follows:

.mag
Magnetization vector of box in units of [mT].

.dim
Magnet dimension=[a,b,c] which correspond to the three side lengths of the box in units

.pos
Position of the center of the magnet in units of [mm].

.rot
Present relative rotation of the magnet, returns a scipy rotation object.

---

It would be nice to have an open discussion with both developers and users to conclude whether this naming proposal is preferable over the new one, or to have the new proposals that may combine the qualities of both.

[traavnik]

I like to make my names just verbose enough to not be ambiguous. Would vote for short form in this case. I also prefer .orient over .rot although it breaks the nice 3 letter pattern. Can’t have everything.

API backward compatibility is not a valid concern to me for a least two reasons. They’re already breaking it by merging .angle and .axis as mentioned in OP. I expect to see some more breaking changes throughout new code (didn’t look). The other reason is convention. Bumping major version number (2.x.x -> 3.x.x) implies API change, which is probably a very conscious and well thought out decision by the authors. On the contrary, it would be very wrong if name change was delayed to any minor version update.

[OrtnerMichael]

completed with #330

• mag -> magnetization
• dim -> dimension or diameter
• pos -> position
• rot -> orientation (source attribute)
• src_typ -> source_type
• pos_pix -> pixel
• rot -> rotation (method argument)
• direc -> show_direction
• size_direc -> size_directions