1. 05 Oct, 2018 15 commits
• ENH: improve, simplify, rationalize coordinate system handling (issue #863) · c75d5118
Mark Olesen authored
```Previously the coordinate system functionality was split between
coordinateSystem and coordinateRotation. The coordinateRotation stored
the rotation tensor and handled all tensor transformations.

The functionality has now been revised and consolidated into the
coordinateSystem classes. The sole purpose of coordinateRotation
is now just to provide a selectable mechanism of how to define the
rotation tensor (eg, axis-angle, euler angles, local axes) for user
input, but after providing the appropriate rotation tensor it has
no further influence on the transformations.

--

The coordinateSystem class now contains an origin and a base rotation
tensor directly and various transformation methods.

- The origin represents the "shift" for a local coordinate system.

- The base rotation tensor represents the "tilt" or orientation
of the local coordinate system in general (eg, for mapping
positions), but may require position-dependent tensors when
transforming vectors and tensors.

For some coordinate systems (currently the cylindrical coordinate system),
the rotation tensor required for rotating a vector or tensor is
position-dependent.

The new coordinateSystem and its derivates (cartesian, cylindrical,
indirect) now provide a uniform() method to define if the rotation
tensor is position dependent/independent.

The coordinateSystem transform and invTransform methods are now
available in two-parameter forms for obtaining position-dependent
rotation tensors. Eg,

... = cs.transform(globalPt, someVector);

In some cases it can be useful to use query uniform() to avoid
storage of redundant values.

if (cs.uniform())
{
vector xx = cs.transform(someVector);
}
else
{
List<vector> xx = cs.transform(manyPoints, someVector);
}

Support transform/invTransform for common data types:
(scalar, vector, sphericalTensor, symmTensor, tensor).

====================
Breaking Changes
====================

- These changes to coordinate systems and rotations may represent
a breaking change for existing user coding.

- Relocating the rotation tensor into coordinateSystem itself means
that the coordinate system 'R()' method now returns the rotation
directly instead of the coordinateRotation. The method name 'R()'
was chosen for consistency with other low-level entities (eg,
quaternion).

The following changes will be needed in coding:

Old:  tensor rot = cs.R().R();
New:  tensor rot = cs.R();

Old:  cs.R().transform(...);
New:  cs.transform(...);

Accessing the runTime selectable coordinateRotation
has moved to the rotation() method:

Old:  Info<< "Rotation input: " << cs.R() << nl;
New:  Info<< "Rotation input: " << cs.rotation() << nl;

- Naming consistency changes may also cause code to break.

Old:  transformVector()
New:  transformPrincipal()

The old method name transformTensor() now simply becomes transform().

====================
New methods
====================

For operations requiring caching of the coordinate rotations, the
'R()' method can be used with multiple input points:

tensorField rots(cs.R(somePoints));

and later

Foam::transformList(rots, someVectors);

The rotation() method can also be used to change the rotation tensor
via a new coordinateRotation definition (issue #879).

The new methods transformPoint/invTransformPoint provide
transformations with an origin offset using Cartesian for both local
and global points. These can be used to determine the local position
based on the origin/rotation without interpreting it as a r-theta-z
value, for example.

================
Input format
================

- Streamline dictionary input requirements

* The default type is cartesian.
* The default rotation type is the commonly used axes rotation
specification (with e1/e2/3), which is assumed if the 'rotation'
sub-dictionary does not exist.

Example,

Compact specification:

coordinateSystem
{
origin  (0 0 0);
e2      (0 1 0);
e3      (0.5 0 0.866025);
}

Full specification (also accepts the longer 'coordinateRotation'
sub-dictionary name):

coordinateSystem
{
type    cartesian;
origin  (0 0 0);

rotation
{
type    axes;
e2      (0 1 0);
e3      (0.5 0 0.866025);
}
}

This simplifies the input for many cases.

- Additional rotation specification 'none' (an identity rotation):

coordinateSystem
{
origin  (0 0 0);
rotation { type none; }
}

- Additional rotation specification 'axisAngle', which is similar
to the -rotate-angle option for transforming points (issue #660).
For some cases this can be more intuitive.

For example,

rotation
{
type    axisAngle;
axis    (0 1 0);
angle   30;
}
vs.
rotation
{
type    axes;
e2      (0 1 0);
e3      (0.5 0 0.866025);
}

- shorter names (or older longer names) for the coordinate rotation
specification.

euler         EulerRotation
starcd        STARCDRotation
axes          axesRotation

================
Coding Style
================
- use Foam::coordSystem namespace for categories of coordinate systems
(cartesian, cylindrical, indirect). This reduces potential name
clashes and makes a clearer declaration. Eg,

coordSystem::cartesian csys_;

The older names (eg, cartesianCS, etc) remain available via typedefs.

- added coordinateRotations namespace for better organization and
reduce potential name clashes.```
• ENH: cylindricalCS is now in radians only (issue #863) · e2182625
Mark Olesen authored
```- this provides internal consistency and allows direct use of the
coordinate angle with sin(), cos() functions.
It eliminates potential issues that could otherwise arise from
alternative user input.

Eg, in mixerFvMesh it would have previously been possible to specify
the coordinate system to use degrees or radians, but these units were
not checked when determining the tangential sweep positions.

NOTE: this may represent a breaking change if user coding has been
relying on cylindrical coordinate system in degrees.```
• ENH: additional constructor and methods for regionProperties · e69c617f
Mark Olesen authored
```- can now construct with READ_IF_PRESENT and use count() to determine
if it was loaded. names() and sortedNames() for a collected overview.```
• ENH: use intermediate constants for sin/cos in coordinate rotations · 0d792cd5
Mark Olesen authored
```- makes an easier overview of the rotation matrix coefficients
(issue #863).

Provided as a distinct commit for easier examination of the lines changed.```
• ENH: expose calculation of coordinate rotations as static methods · 59fa3c9d
Mark Olesen authored
`- improve handling of degenerate cases for the two-axes specification.`
• ENH: add GeometricField constructor for movable internal field · 2f13f082
Mark Olesen authored
`- the movable type is List&& or Field&&`
• ENH: generalize instant to be templated, movable, etc · ea634867
Mark Olesen authored
`- allows reuse for other purposes`
• ENH: fileName hasPath(), removePath() methods · 42532249
Mark Olesen authored
`- improved move constructors/assignments for fileName, string, etc`
• ENH: use dictionary::readEntry for detection of input errors (#762, #1033) · 392ef54c
Mark Olesen authored
```- instead of   dict.lookup(name) >> val;

for checking of input token sizes.
This helps catch certain types of input errors:

{

key1 ;                // <- Missing value
key2 1234             // <- Missing ';' terminator
key3 val;
}

STYLE: readIfPresent() instead of 'if found ...' in a few more places.```
• ENH: dictionary lookup with detection of zero tokens (#1033) · 45c8503c
Mark Olesen authored
```- the opposite problem from issue #762. Now we also test if the input
token stream had any tokens at all.

- called by the dictionary get<> and readEntry() methods.```
2. 04 Oct, 2018 9 commits
3. 03 Oct, 2018 4 commits
4. 02 Oct, 2018 3 commits
5. 28 Sep, 2018 6 commits
6. 27 Sep, 2018 3 commits