Mathematical notation, more convenient random(), inv() equal to "~"

hakonanes commented 7 months ago

Description of the change

This PR contains several improvements, most notably adding a consistent mathematical notation. I realize that capitalized variable names, especially just O (for orientations), are frowned upon. Just see the PEP 8 style guide which we follow closely... I'm open to changing the notation. The notation is listed in the contributing guide.

Other additions:

Added Vector3d.random() and Miller.random() (accepting phase) returning unit vectors. Achieved by moving the current random() implementation from Quaternion to Object3d.
Orientation.random() and Misorientation.random() accept symmetry arguments. The returned unit (mis)orientations are not reduced to the fundamental zone. This could be added with a boolean parameter.
inv() method for Quaternion, Rotation, Orientation, and Misorientation. Its behavior is identical to the inversion operator ~. For misorientations, it also swaps the symmetries, in line with inverting the direction of the basis transformation. Convenient for chaining operations instead of adding parentheses (~M) etc.
Removed orix.base module and moved the Object3d and DimensionError classes to orix._base. This module should never have been part of the public API in the first place. It will now be hidden from the API.
Allow passing a tuple of integers to the reshape() method of 3D objects. This has bugged me, that we have unpack a tuple of integers when reshaping an object. It is now unnecessary. We can pass (1) a single tuple, or (2) multiple integers as separate "arguments" (*args).

Changes:

Fixed the example on combining rotations (added by me) which wrongly stated that that rotations are combined from the left. They are of course combined from the right. Thankfully, this example has not been part of the "stable" docs.
The random() method no longer accepts a list as a valid shape (a tuple or integer is required). This is in line with NumPy's random() function.
Increase minimal version of Matplotlib to >= 3.5 so that we can pass plt.figure(layout="tight") when creating figures internally.
Sorted code in classes into the following sections, making the code much easier to navigate:
1. Properties
2. Dunder (double underscore) methods
3. Class methods
4. All to_*() methods, if any
5. Other public methods
6. Other private methods
Include inherited members in API reference without the need for "duplication" of code. We previously excluded inherited members because the API of classes extending Matplotlib's Axes or Axes3D got cluttered with unnecessary attributes and methods. I've added a hook into autodoc called autodoc-skip-member that tries its best to include only attributes/properties and methods that are defined in orix.

Progress of the PR

[x] Docstrings for all functions
[x] Unit tests with pytest for all lines
[x] Clean code style by running black via pre-commit
[x] Update tutorials and examples
[x] Finish mathematical notation
Figure out whether Vector3d.random() or sample_S2_random_mesh() should be used: Let's do this in a separate PR
[x] Clean up API reference

Minimal example of the bug fix or new feature

>>> import numpy as np
>>> from orix.crystal_map import Phase
>>> from orix.quaternion import Misorientation, Orientation, symmetry
>>> from orix.vector import Miller, Vector3d

>>> v = Vector3d.random(100)
>>> np.isclose(v.norm, 1).all()
True
>>> _ = v.reshape((10, 10)).reshape(4, 5, 5)

>>> cubic = Phase(point_group="m-3m")
>>> g = Miller.random(cubic, (2, 3), "hkl")
>>> g
Miller (2, 3), point group m-3m, hkl
[[[ 0.6439 -0.2434 -0.7253]
  [-0.5368  0.7654 -0.3549]
  [-0.3677  0.925  -0.0951]]
 [[-0.2624 -0.2891 -0.9206]
  [ 0.8905 -0.3044 -0.3382]
  [-0.2024 -0.8396 -0.504 ]]]

>>> O = Orientation.random(5, symmetry.Oh)
>>> M1 = Misorientation(O * O.inv())
>>> M1
Misorientation (5,) 1
[[ 1.  0.  0.  0.]
 [ 1.  0. -0.  0.]
 [ 1.  0.  0.  0.]
 [ 1.  0.  0.  0.]
 [ 1.  0.  0.  0.]]

>>> M2 = Misorientation.random(5, (symmetry.Oh, symmetry.D6h))
>>> M2
Misorientation (5,) m-3m, 6/mmm
[[ 0.9342  0.356   0.0032  0.0242]
 [-0.724   0.5373  0.2002  0.3835]
 [ 0.108   0.7762  0.1533 -0.6019]
 [ 0.3663 -0.2224  0.5108  0.7452]
 [-0.4543 -0.7006 -0.4017  0.376 ]]

>>> M2.inv()
Misorientation (5,) 6/mmm, m-3m
[[ 0.9342 -0.356  -0.0032 -0.0242]
 [-0.724  -0.5373 -0.2002 -0.3835]
 [ 0.108  -0.7762 -0.1533  0.6019]
 [ 0.3663  0.2224 -0.5108 -0.7452]
 [-0.4543  0.7006  0.4017 -0.376 ]]

For reviewers

[x] The PR title is short, concise, and will make sense 1 year later.
[ ] New functions are imported in corresponding __init__.py.
[ ] New features, API changes, and deprecations are mentioned in the unreleased section in CHANGELOG.rst.
[ ] Contributor(s) are listed correctly in __credits__ in orix/__init__.py and in .zenodo.json.

review-notebook-app[bot] commented 7 months ago

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

hakonanes commented 7 months ago

I'm sorry for the size of this PR. If necessary, I can split it into several smaller ones.

Nonetheless, everything is detailed in the top comment. And notebook changes can easily be reviewed at ReviewNB.

pc494 commented 7 months ago

I am happy to review this over the weekend.

hakonanes commented 7 months ago

Thank you for having a look, Phillip, really appreciate it. Yes, I'll make coming PRs much more manageable.

pyxem / orix