Merge pull request #116 from ModiaSim/hidden_states

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

.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

Project.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"

README.md

@@ -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]),

create_Modia3D_sysimage.jl

@@ -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

docs/make.jl

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

docs/src/Components/Joints.md

@@ -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/src/Functions.md

@@ -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/index.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.

docs/src/tutorial/CollisionHandling.md

@@ -13,26 +13,26 @@ using Modia3D
 
 BouncingSphere = Model3D(
     boxHeigth = 0.1,
-    world      = Object3D(feature=Scene(enableContactDetection = true,
-                    animationFile = "BouncingSphere.json")),
+    world      = Object3D(feature=Scene(enableContactDetection = true, # default value
+                        animationFile="BouncingSphere.json")),
     ground     = Object3D(parent=:world, translation=:[0.0,-boxHeigth/2,0.0],
                     feature=Solid(shape=Box(lengthX=4.0, lengthY=:boxHeigth, lengthZ=0.7),
                         visualMaterial=VisualMaterial(color="DarkGreen"),
-                        solidMaterial="Steel",
-                        collision=true)),
-    sphere     = Object3D(feature=Solid(shape=Sphere(diameter=0.2),
+                        solidMaterial="Steel", # for mass and force computation
+                        collision=true)),      # enable collision flag
+    sphere     = Object3D(parent=:world, fixedToParent=false, translation=[0.0, 1.0, 0.0],
+                        feature=Solid(shape=Sphere(diameter=0.2),
                         visualMaterial=VisualMaterial(color="Blue"),
-                        solidMaterial="Steel",
+                        solidMaterial="Steel", # for mass and force computation
                         massProperties=MassPropertiesFromShapeAndMass(mass=0.001),
-                        collision=true)),
-    free       = FreeMotion(obj1=:world, obj2=:sphere, r=Var(init=[0.0, 1.0, 0.0]))
+                        collision=true)),      # enable collision flag
 )
 
 bouncingSphere = @instantiateModel(BouncingSphere, unitless=true)
 simulate!(bouncingSphere, stopTime=2.2, dtmax=0.1)
 
 @usingModiaPlot
-plot(bouncingSphere, "free.r", figure=1)
+plot(bouncingSphere, "sphere.translation", figure=1)
 
 end
 ```

palettes/contactPairMaterials.json

@@ -35,6 +35,18 @@
     "slidingFrictionCoefficient": 0.0,
     "rotationalResistanceCoefficient": 0.0
     },
+    "BilliardTable,BilliardCue": {
+        "responseType": "ElasticResponse",
+        "coefficientOfRestitution": 0.0,
+        "slidingFrictionCoefficient": 0.8,
+        "rotationalResistanceCoefficient": 0.01
+    },     
+    "BilliardCue,BilliardCue": {
+    "responseType": "ElasticResponse",
+    "coefficientOfRestitution": 0.98,
+    "slidingFrictionCoefficient": 0.0,
+    "rotationalResistanceCoefficient": 0.0
+    },
     "Observer,Steel": {
         "responseType": "ObserverResponse",
         "printAlarm": true

src/Composition/_module.jl

@@ -22,6 +22,7 @@ module Composition
 
 export MultibodyData
 
+export instantiateModel3D!
 export initialize, initAnalysis!, performAnalysis!, closeAnalysis!, visualize!, visualizeWorld!
 export updatePosition!, update!
 export RotationVariables, RCardan123
@@ -36,10 +37,12 @@ export setStatesRevolute!  , setAccelerationsRevolute!  , getGenForcesRevolute
 export setStatesPrismatic! , setAccelerationsPrismatic! , getGenForcesPrismatic
 export setStatesFreeMotion!, setAccelerationsFreeMotion!, getGenForcesFreeMotion
 export setStatesFreeMotion_isrot123!
+export setHiddenStatesDerivatives!, getGenForcesHiddenJoints
+export J123, J132, J123or132
 
 export computeGeneralizedForces!
 
-export distanceAndAngles, distance, planarRotationAngle
+export distanceAndAngles, distance
 export measFrameRotation, measFramePosition, measFrameDistance
 export measFrameRotVelocity, measFrameTransVelocity, measFrameDistVelocity
 export measFrameRotAcceleration, measFrameTransAcceleration, measFrameDistAcceleration