Merge pull request #116 from ModiaSim/hidden_states

Object3D that is fixed or freely moving with respect to parent and other improvements.

Author: MartinOtter

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.7.2'
+          - '1.7.3'
         os:
           - ubuntu-latest
           - windows-latest

Manifest.toml

@@ -1,7 +1,7 @@
 authors = ["Andrea Neumayr <[email protected]>", "Martin Otter <[email protected]>", "Gerhard Hippmann <[email protected]>"]
 name = "Modia3D"
 uuid = "07f2c1e0-90b0-56cf-bda7-b44b56e34eed"
-version = "0.10.4"
+version = "0.11.0"
 
 [compat]
 Colors = "0.12, 0.11, 0.10"
@@ -12,7 +12,7 @@ HTTP = "0.9"
 JSON = "0.21"
 Measurements = "2"
 MeshIO = "0.4.10"
-Modia = "0.8.3"
+Modia = "0.9.1"
 MonteCarloMeasurements = "1"
 OrderedCollections = "1"
 Reexport = "1.0"

Project.toml

@@ -29,6 +29,7 @@ Note, Modia3D reexports the following definitions
 - `using Modia`
 - `using Unitful`
 - `using DifferentialEquations`
+- `using SignalTables`
 - and exports functions `CVODE_BDF` and `IDA` of [Sundials.jl](https://github.com/SciML/Sundials.jl).
 
 As a result, it is usually sufficient to have `using Modia3D` in a model to utilize the relevant 
@@ -57,7 +58,8 @@ Modia3D has various *3D animation features*:
 
 ## Faster Startup
 
-In order to speed up startup, it is adviced to generate a sysimage by executing the following commands:
+In order to speed up startup, a sysimage can be generated by executing the following commands
+(may take several minutes):
 
 ```julia
 julia
@@ -66,7 +68,7 @@ include("$(Modia3D.path)/create_Modia3D_sysimage.jl")
 exit()
 ```
 
-This will include a file `Modia3D_sysimage.dll` (on Windows) or `Modia3D_sysimage.so` (otherwise) in your
+This will generate a file `Modia3D_sysimage.dll` (on Windows) or `Modia3D_sysimage.so` (otherwise) in your
 current working directory that includes all packages of your current project and the following packages
 (these packages are added to your current project, if not yet included):
 
@@ -79,6 +81,10 @@ julia -JModia3D_sysimage.dll (on Windows)
 julia -JModia3D_sysimage.so  (otherwise)
 ```
 
+The benefit is that `using Modia3D` is nearly immediatedly executed (instead of > 30 seconds).
+The drawback is that `create_Modia3D_sysimage.jl` has to be newly executed, whenever
+new package versions are used in your environment.
+
 ## Main Developers and License
 
 [Andrea Neumayr](mailto:[email protected]),

README.md

@@ -9,7 +9,7 @@
 # to generate a sysimage of your current project and store it in your current working directory.
 # Before generating the sysimage, the following packages are added to your current project (if not yet included):
 #
-#    Modia, Modia3D, ModiaPlot_PyPlot, PackageCompiler, Revise
+#    Modia, Modia3D, SignalTablesInterface_PyPlot, PackageCompiler, Revise
 #
 module Create_Modia3D_sysimage
 
@@ -21,7 +21,7 @@ import Pkg
 project     = Pkg.project()
 projectPath = project.path
 availablePackages = keys(project.dependencies)
-addPackages       = setdiff!(["Modia", "Modia3D", "ModiaPlot_PyPlot", "PackageCompiler", "Revise"], availablePackages)
+addPackages       = setdiff!(["Modia", "Modia3D", "SignalTablesInterface_PyPlot", "PackageCompiler", "Revise"], availablePackages)
 println("!!! Creating sysimage for Modia3D (executing: $file)")
 println("!!! This will include all packages from project $projectPath")
 if length(addPackages) > 0

create_Modia3D_sysimage.jl

@@ -22,6 +22,7 @@ makedocs(
         "Components/GravityField.md"
         "Components/ForceElements.md"
      ],
+     "Functions" => "Functions.md",
      "Internal" => [
         "internal/Profiling.md"
         "internal/DynamicDispatch.md"

docs/make.jl

@@ -19,7 +19,9 @@ Prismatic
 
 
 
-## FreeMotion
+## FreeMotion (deprecated)
+
+Do no longer use FreeMotion joints, but instead use [`Object3D`](@ref) with `fixedToParent=false`.
 
 ```@docs
 FreeMotion

docs/resources/images/Tutorial/bouncingSphere.png

@@ -0,0 +1,137 @@
+# Functions
+
+```@meta
+CurrentModule = Modia3D
+```
+
+## 3D Vectors
+
+Functions to construct 3D vectors `v::SVector{3,F}`.
+
+```@docs
+ZeroVector3D
+axisValue
+```
+
+## Rotation Matrices
+
+Functions to construct rotation matrices `R::SMatrix{3,3,F,9}` rotating a 
+coordinate-system/frame 1 into a coordinate-system/frame 2.
+
+| Function                                         | Description                                        |
+|:-------------------------------------------------|:---------------------------------------------------|
+| [`Modia3D.NullRotation`](@ref)(::Type{F})        | No rotation from frame 1 to frame 2                |
+| [`Modia3D.assertRotationMatrix`](@ref)(R)        | Assert that R is a rotation matrix                 |
+| [`Modia3D.rot1`](@ref)(angle)                    | Rotate around `angle` along x-axis                 |
+| [`Modia3D.rot2`](@ref)(angle)                    | Rotate around `angle` along y-axis                 |
+| [`Modia3D.rot3`](@ref)(angle)                    | Rotate around `angle` along z-axis                 |
+| [`Modia3D.rot123`](@ref)(angle1, angle2, angle3) | Rotate around angles along x,y,z-axes              |
+| [`Modia3D.rot123`](@ref)(angles)                 | Rotate around angles along x,y,z-axes              |
+| [`Modia3D.rotAxis`](@ref)(axis,angle)            | Rotate around `angle` along `axis` (= 1,2,3)       |
+| [`Modia3D.rotAxis`](@ref)(axis,positive,angle)   | Rotate around `angle` if `positive`, else `-angle` |
+| [`Modia3D.rot_e`](@ref)(e, angle)                | Rotate around `angle` along unit vector `e`        |
+| [`Modia3D.rot_nxy`](@ref)(nx, ny)                | `nx`/`ny` are in x/y-direction of frame 2          |
+| [`Modia3D.from_q`](@ref)(q)                      | Return rotation matrix from quaternion `q`         |
+
+
+Examples
+
+```julia
+using Modia3D
+
+# R1,R2,R3 are the same RotationMatrices
+R1 = Modia3D.rot1(pi/2)
+R2 = Modia3D.rot1(90u"°")
+R3 = Modia3D.rot_e([1,0,0], pi/2)
+```
+
+```@docs
+NullRotation
+assertRotationMatrix
+rot1
+rot2
+rot3
+rot123
+rotAxis
+rot_e
+rot_nxy
+from_q
+```
+
+## Quaternions
+
+Functions to construct quaternions `q::SVector{4,F}` rotating a 
+coordinate-system/frame 1 into a coordinate-system/frame 2.
+
+| Function                                          | Description                                |
+|:--------------------------------------------------|:-------------------------------------------|
+| [`Modia3D.NullQuaternion`](@ref)(::Type{F})       | No rotation from frame 1 to frame 2        |
+| [`Modia3D.assertQuaternion`](@ref)(q)             | Assert that q is a quaternion              |
+| [`Modia3D.qrot1`](@ref)(angle)                    | Rotate around `angle` along x-axis         |
+| [`Modia3D.qrot2`](@ref)(angle)                    | Rotate around `angle` along y-axis         |
+| [`Modia3D.qrot3`](@ref)(angle)                    | Rotate around `angle` along z-axis         |
+| [`Modia3D.qrot123`](@ref)(angle1, angle2, angle3) | Rotate around angles along x,y,z-axes      |
+| [`Modia3D.qrot_e`](@ref)(e, angle)                | Rotate around `angle` along unit vector `e`|
+| [`Modia3D.qrot_nxy`](@ref)(nx, ny)                | `nx`/`ny` are in x/y-direction of frame 2  |
+| [`Modia3D.from_R`](@ref)(R)                       | Return `q` from rotation matrix `R`        |
+
+
+```@docs
+NullQuaternion
+assertQuaternion
+qrot1
+qrot2
+qrot3
+qrot123
+qrot_e
+qrot_nxy
+from_R
+```
+
+## Frame Transformations
+
+Functions to transform vectors, rotation matrices, quaternions between coordinate systems
+and functions to determine properties from coordinate system transformations.
+
+| Function                                         | Description                                   |
+|:-------------------------------------------------|:----------------------------------------------|
+| [`Modia3D.resolve1`](@ref)(rot, v2)              | Transform vector `v` from frame 2 to frame 1  |
+| [`Modia3D.resolve2`](@ref)(rot, v1)              | Transform vector `v` from frame 1 to frame 2  |
+| [`Modia3D.absoluteRotation`](@ref)(rot01, rot12) | Return rotation 0->2 from rot. 0->1 and 1->2  |
+| [`Modia3D.relativeRotation`](@ref)(rot01, rot02) | Return rotation 1->2 from rot. 0->1 and 0->2  |
+| [`Modia3D.inverseRotation`](@ref)(rot01)         | Return rotation 1->0 from rot, 0->1           |
+| [`Modia3D.planarRotationAngle`](@ref)(e,v1,v2)   | Return angle of planar rotation along `e`     |
+| [`Modia3D.eAxis`](@ref)(axis)                    | Return unit vector `e` in direction of `axis` |
+| [`Modia3D.skew`](@ref)(v)                        | Return skew-symmetric matrix of vector v      |
+
+```@docs
+resolve1
+resolve2
+absoluteRotation
+relativeRotation
+inverseRotation
+planarRotationAngle
+eAxis
+skew
+```
+
+## Frame Interpolations
+
+Given a set of coordinate-systems/frames by a vector `r` of position vectors (to their origins) and
+and an optional vector `q` of Quaternions (of their absolute orientations), then
+the following functions interpolate linearly in these frames:
+
+| Function                                        | Description                                    |
+|:------------------------------------------------|:-----------------------------------------------|
+| [`Modia3D.Path`](@ref)(r,q)                     | Return path defined by a vector of frames      |
+| [`Modia3D.t_pathEnd`](@ref)(path)               | Return path parameter `t_end` of last frame    |
+| [`Modia3D.interpolate`](@ref)(path,t)           | Return `(rt,qt)` of Path at path parameter `t` |
+| [`Modia3D.interpolate_r`](@ref)(path,t)         | Return `rt` of Path at path parameter `t`      |
+
+
+```@docs
+Path
+t_pathEnd
+interpolate
+interpolate_r
+```

docs/src/Components/Joints.md

@@ -54,7 +54,7 @@ Modia3D has various *3D animation features*:
 
 ## Faster Startup
 
-In order to speed up startup, it is adviced to generate a sysimage by executing the following commands:
+In order to speed up startup a sysimage can be generated by executing the following commands:
 
 ```julia
 julia
@@ -67,7 +67,7 @@ This will include a file `Modia3D_sysimage.dll` (on Windows) or `Modia3D_sysimag
 current working directory that includes all packages of your current project and the following packages
 (these packages are added to your current project, if not yet included):
 
-- Modia, Modia3D, ModiaPlot_PyPlot, PackageCompiler, Revise
+- Modia, Modia3D, SignalTablesInterface_PyPlot, PackageCompiler, Revise
 
 Start julia with this sysimage in the following way:
 
@@ -93,6 +93,59 @@ julia -JModia3D_sysimage.so  (otherwise)
 
 ## Release Notes
 
+
+### Version 0.11.0
+
+- Requires Modia 0.9.1 or later.
+
+- Additional keyword arguments of Object3D: `Object3D(..., fixedInParent=true, velocity=[0.0, 0.0, 0.0], angularVelocity=[0.0, 0.0, 0.0])`,
+  besides the existing `parent, translation, rotation, feature`. A freely moving Object3D is defined with
+  `Object3D(..., fixedInParent=false, ...)`, where `velocity=.., angularVelocity=..`
+  are the initial conditions (resolved in the parent frame). For more details, see [`Object3D`](@ref).\
+  The states and other code for such Object3Ds are *not* part of the generated code
+  (so compilation is faster, and the objects can be changed after code generation).
+
+- The `FreeMotion` joints in all test models have been removed and replaced by Object3Ds with `fixedInParent=false`.
+  A new test model test/Basic/FreeShaftAdaptiveRotSequenceWithFreeMotion.jl has been introduced with a `FreeMotion`
+  joint, to still have one test for a `FreeMotion` joint.
+
+- `Revolute(..)` and `Prismatic(..)` joints can define axis of rotation/translation optionally as vector, e.g., `axis = [1.0, 2.0, 3.0]`.
+
+- New function `Modia3D.rot1(angle,v)` which is an efficient implementation of `Modia3D.rot1(angle)*v` where `rot1(angle)` returns
+  a transformation matrix and `v` is a vector and `rot1(angle,v)` returns the product of the transformation matrix and a vector
+  in an efficient way. Correspondingly, there are new functions
+  `Modia3D.rot2(angle,v), Modia3D.rot3(angle,v), Modia3D.resolve1(rotation,v2), Modia3D.resolve2(rotation,v1)`.
+
+- Simulation speed improved, if contact of FileMesh objects.
+
+- contactPairMaterials.json updated with more material pairs (e.g. results in less warning messages for runtests).
+
+- New file `Modia3D.create_Modia3D_sysimage.jl` to create a *sysimage*. Using this sysimage has the
+  advantage that `using Modia3D` is nearly immediatedly executed (instead of > 30 seconds). 
+  For details, see README.md file.
+  
+- Internal: Timer included in Scene (scene.timer), so that a timer is more easily accessible for debugging.
+
+- Internal: Cleanup and improvements of Modia3D/src/Frames.jl 
+
+
+**Deprecated**
+
+- Joint `FreeMotion` is **deprecated**. Use instead `Object3D(..., fixedInParent=false, ...)`.
+  Note, Object3D has variables `translation, rotation, velocity, angularVelocity, rotationXYZ` instead of 
+  `r, rot, v, w, isrot123` of `FreeMotion`.
+  Furthermore, `angularVelocity` is resolved in the parent `Object3D` whereas `w` in `FreeMotion(obj1=.., obj2=..., ..)` is resolved in
+  `obj2` and not in `obj1`. This means in particular that the init/start value `FreeMotion(.., w=Var(start=w_start)...)` needs
+  to be transformed in Object3D with `Object3D(..., fixedInParent=false, rotation=XXX, angularVelocity = Modia3D.resolve1(XXX,w_start))`
+  and the results of `angularVelocity` will be different to `w` because resolved in different coordinate systems.
+
+**Non-backwards compatible changes**
+
+- Since Modia3D 0.11.0 is based on Modia 0.9.0, the non-backwards compatible changes of Modia have also an effect on Modia3D
+  (for details, see the [release notes of Modia 0.9.0](https://github.com/ModiaSim/Modia.jl/releases/tag/v0.9.0)). 
+  Typically, this should give problems only in seldomly occuring corner cases.
+ 
+
 ### Version 0.10.4
 
 - Script `Modia3D/create_Modia3D_sysimage.jl` improved.