diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index e257bfdb..db60e9fc 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -4,10 +4,11 @@ Welcome to ModelOrderReduction's documentation! .. toctree:: :maxdepth: 2 - usage/install/install - usage/tutorial/tutorial - usage/examples/examples - tools + usage/install/install + usage/principle/principle + usage/howToUse/howToUse + usage/examples/examples + tools .. components Indices and tables diff --git a/doc/sphinx/source/usage/examples/Diamond/diamond.md b/doc/sphinx/source/usage/examples/Diamond/diamond.md index ef8b62ff..1e6deb35 100644 --- a/doc/sphinx/source/usage/examples/Diamond/diamond.md +++ b/doc/sphinx/source/usage/examples/Diamond/diamond.md @@ -37,7 +37,7 @@ After that with a raisonnable tolerance (here *0.001*) we will select different ![Diamond robot modes](DiamondRobot_modes_5367x1342.png) -With these different parameters we will after perform the reduction like explained {doc}`here ` +With these different parameters we will after perform the reduction like explained {doc}`here ` ## Results @@ -54,4 +54,4 @@ exemple results with a fine mesh: For more details about the results, displacmeent error comparison, test with different mesh and other, you can read the paper affiliated with this plugin{footcite:ps}`Goury2018`. ```{footbibliography} -``` \ No newline at end of file +``` diff --git a/doc/sphinx/source/usage/examples/Sofia/sofia.md b/doc/sphinx/source/usage/examples/Sofia/sofia.md index 3129ad58..ee74fd1d 100644 --- a/doc/sphinx/source/usage/examples/Sofia/sofia.md +++ b/doc/sphinx/source/usage/examples/Sofia/sofia.md @@ -35,7 +35,7 @@ We have only one actuator here, so our *listObjToAnimate* contains only one obje ObjToAnimate("actuator","doingCircle",'MechanicalObject',incr=0.05,incrPeriod=3,rangeOfAction=6.4,dataToWorkOn="position",angle=0,rodRadius=0.7) -With these different parameters we will after perform the reduction like explained {doc}`here ` +With these different parameters we will after perform the reduction like explained {doc}`here ` ## Results diff --git a/doc/sphinx/source/usage/examples/Starfish/starfish.md b/doc/sphinx/source/usage/examples/Starfish/starfish.md index 0e38d935..d062a540 100644 --- a/doc/sphinx/source/usage/examples/Starfish/starfish.md +++ b/doc/sphinx/source/usage/examples/Starfish/starfish.md @@ -31,7 +31,7 @@ After that with a raisonnable tolerance (here *0.001*) we will select different ![Starfish robot modes](SartfishRobot_modes.png) -With these different parameters we will after perform the reduction like explained {doc}`here `. +With these different parameters we will after perform the reduction like explained {doc}`here `. ## Results @@ -50,4 +50,4 @@ you can read the paper affiliated with this plugin{footcite:ps}`Goury2018`. ```{footbibliography} -``` \ No newline at end of file +``` diff --git a/doc/sphinx/source/usage/howToUse/howToReduce_gui.md b/doc/sphinx/source/usage/howToUse/howToReduce_gui.md new file mode 100644 index 00000000..40c42d9c --- /dev/null +++ b/doc/sphinx/source/usage/howToUse/howToReduce_gui.md @@ -0,0 +1,13 @@ +# Using GUI + +## gui_modelOrderReduction.py + +tutorial about the gui + +🚧 + +## TEST + +tutorial about the gui + +🚧 diff --git a/doc/sphinx/source/usage/howToUse/howToReduce_script.md b/doc/sphinx/source/usage/howToUse/howToReduce_script.md new file mode 100644 index 00000000..942afadb --- /dev/null +++ b/doc/sphinx/source/usage/howToUse/howToReduce_script.md @@ -0,0 +1,153 @@ +# Using script + +## Python: modelOrderReduction.py + +In the root of the */tools* folder there is a python file called **modelOrderReduction.py**. +In it, there are already several parameters allowing to reduce, if un-commented, the different +examples that are present in */examples* by giving the path to the corresponding SOFA scene with the variable `originalScene`. + +To understand and know how to use the different parameters you can refer to the following section +that is just a copy/paste of what you can find in the noteBook. + +The noteBook is great to understand what's happening by performing reduction on the given examples +but after that it is much more practical to use **modelOrderReduction.py** to do your own reduction. + +To proceed you need to add and fill the following variable according to the scene you want to reduce: +```python +nodeToReduce = '/PathToNodeToReduce' +myAnim1 = ObjToAnimate("pathToComponentToAnimate","animationFctYouWillAnimateWith", + incr=1,incrPeriod=2,rangeOfAction=10,dataToWorkOn="onWhichDataFieldYouWillWork", + kwargs=...) #additionalArgumentSpecificToTheAnimationFct +myAnim2 = ... +. +. +listObjToAnimate = [myAnim1,myAnim2,...] +addRigidBodyModes = [0,0,0] # add translation dof in your reduce model in the different axis if put to 1 if not will stay fixed +``` + +Then we recommend if it's the first time you reducing a particular model, to proceed step by step by uncommenting the different phase instead +of using `reduceMyModel.performReduction()` which will do them all in one go. + +```python +reduceMyModel.phase1() +#reduceMyModel.phase2() +#reduceMyModel.phase3() +#reduceMyModel.phase4() +``` + +This way you will be able to check any issue along the way. Particularly after `phase1` & `phase3` where we launch SOFA +with the animation parameters you've given. In the batch you will have the following display: + +```batch +periodSaveGIE : 6 | nbTrainingSet : 8 | nbIterations : 89 +################################################## +[133985141249600] processing threaded sofa task in: /tmp/sofa-launcher-6a70jp_x/phase1_snapshots.py +[133983935379008] processing threaded sofa task in: /tmp/sofa-launcher-ma1p72bd/phase1_snapshots.py +. +. +``` + +This means that it's creating multiple instance of your scene with different animation configuration and playing +them in parallel to get out of it data to construct the reduced model. +So if at the end of `phase1` & `phase3` you have error don't hesitate to go into these temporary folders to see directly what's happening really. +Most probably the animation is not well configured or the modification of your intial scene went wrong. +If `phase1` & `phase3` went well `phase2` & `phase4` should to. + +After `phase4`, in the folder you have chosen to put the reduction results, you should now have a file named **reduced_packageName.py**. +This python file try to create a function allowing you to instantiate easily the reduce model into your previous scene: + +```python +def Reduced_test( + attachedTo=None, + name="Reduced_test", + rotation=[0.0, 0.0, 0.0], + translation=[0.0, 0.0, 0.0], + scale=[1.0, 1.0, 1.0], + surfaceMeshFileName=False, + surfaceColor=[1.0, 1.0, 1.0], + nbrOfModes=32, + hyperReduction=True): + modelRoot = attachedTo.addChild(name) + . + . + . + return modelNode +``` + +:::{warning} +The creation of this function is a complicated process and is prone to errors. +This is just a tool to help you but keep in mind that the real reduced model is contained +in the **/data** folder produced after the reduction, you "just" need to give the data files to the MOR component. +To the **hyperreduced forcefield** the *modes*, *RID* and *weights* files. To the **ModelOrderReductionMapping** the *modes* file only. +```python +modelNode.addObject('HyperReducedTetrahedronFEMForceField' , + nbModes = nbrOfModes, performECSW = True, + modesPath = path + '/data/modes.txt', + RIDPath = path + '/data/reducedFF_modelNode_0_RID.txt', + weightsPath = path + '/data/reducedFF_modelNode_0_weight.txt') +modelNode.addObject('ModelOrderReductionMapping' , + input = '@../MechanicalObject', output = '@./dofs', + modesPath = path + '/data/modes.txt') +``` +::: + +At the end of this file there is a generic scene that is created to test it: + +```python +def createScene(rootNode): + surfaceMeshFileName = False + + MainHeader(rootNode,plugins=["SoftRobots","ModelOrderReduction"], + dt=1.0, + gravity=[0.0, 0.0, -9810.0]) + rootNode.VisualStyle.displayFlags="showForceFields" + + Reduced_test(rootNode, + name="Reduced_test", + surfaceMeshFileName=surfaceMeshFileName) +``` + +:::{warning} +The behavior is generic so it can be normal that you have a different behavior compared to your original scene, this one is just for testing. +::: + +You can now `import Reduced_test` anywhere to use it either into your original scene or some new ones. + +## NoteBook: modelOrderReduction.ipynb + +```{note} +The following tutorial comes from a python-notebook. +If you want to make the tutorial interactively go directly to: + +``/ModelOrderReduction/tools/notebook`` + +then, if you have installed jupyter like explained in the requirement, open a terminal there and launch a session: + +``jupyter notebook`` + +It will open in your web-browser a tab displaying the current files in the directory. Normally you should have one called **modelOrderReduction.ipynb** + +You can click on it and follow the tutorial +``` + +```{toctree} +:maxdepth: 2 + +noteBook + +``` + +## Manually + +The 2 methods presented previously and the API used can help you create your reduced model but depending on +your situation it may not be suited. + +Instead you still have the possibility to perform all of this manually. +- Launch your scene put the component **writeState** in it, run it and stimulate your model as you want (with script or mouse interaction). +- Get the resulting state file, give it to the script {py:meth}`mor.reduction.script.readStateFilesAndComputeModes` to compute the modes +- Then with these modes re-launch your scene after changing it to have a mapping with **modelorderreductionmapping** between +your full model and the modes and change your forcefield for an hyperreduced one specifying `prepareECSW=True` run it, and try stimulating preferably the same way as before. +It will this time generate a **GIE** file. +- Give it to the script {py:meth}`mor.reduction.script.readGieFileAndComputeRIDandWeights` to compute the RID & weights. + +You now have all you need for your reduce model ! Change your original scene with MOR component and give them the different data produced. diff --git a/doc/sphinx/source/usage/howToUse/howToUse.rst b/doc/sphinx/source/usage/howToUse/howToUse.rst new file mode 100644 index 00000000..00cf341f --- /dev/null +++ b/doc/sphinx/source/usage/howToUse/howToUse.rst @@ -0,0 +1,32 @@ +How to use +=========== + +Reduce a model +----------------- + +As explained in the principle section there are 2 main phase to produce the reduced model : + +- First reduction to have a reduce basis thanks to modes +- Second do a hyper-reduction on first reduction + +Using SOFA we will do this in 4 step as described with the following figure : + +.. image:: ../images/MOR_plugin_execution_v2.png + +This different step will alternate between using SOFA to generate data from a given shaking and external python script to extract from this data modes then RID & weights. +We have developed several ways to do this arduous process in a more user friendly ways : + +.. toctree:: + :maxdepth: 1 + + howToReduce_script + howToReduce_gui + +Tutorial video how to +---------------------- + +.. raw:: html + + +

+ diff --git a/doc/sphinx/source/usage/howToUse/noteBook.md b/doc/sphinx/source/usage/howToUse/noteBook.md new file mode 100644 index 00000000..55fbcff5 --- /dev/null +++ b/doc/sphinx/source/usage/howToUse/noteBook.md @@ -0,0 +1,243 @@ +# Model Order Reduction NoteBook + +## Introduction + +In this python notebook exemple we will see with 2 real examples how to reduce a model from one of your sofa scene thanks to the **Model Order Reduction** plugin done by the INRIA research team **Defrost**. + +the two examples will be : + +- **[A cable-driven silicone robot](https://modelorderreduction.readthedocs.io/en/latest/usage/examples/Diamond/diamond.html)** (*paper link : [C. Duriez, ICRA, 2013](https://hal.archives-ouvertes.fr/hal-00823766/document)*). + +![Diamond robot](../examples/Diamond/diamondReal.png) + +- **[A pneumatic Soft Robot](https://modelorderreduction.readthedocs.io/en/latest/usage/examples/Starfish/starfish.html)** (*paper link : Multigait soft Robot [R.F. Shepherd et al, PNAS, 2011](http://www.pnas.org/content/108/51/20400)*). + +![Starfish robot](../examples/Starfish/Starfish_Real.png) + +After these expample presentation we can now proceed to the reduction. +First we have to prepare it by setting a bunch of parameters while explaining there purpose (here the parameters will be set twice, one for the diamond and one for the starfish so you will be able to switch easily between each example) + +## User Paramters + +Before defining the reduction parameters, here are some "import" commands that will be useful for this python notebook: + + +```python +# Import +import os +import sys + +sys.path.append(os.getcwd()+'/../python') + +# MOR IMPORT +from mor.gui import utility +from mor.reduction import ReduceModel +from mor.reduction.container import ObjToAnimate +``` + +### 1. Paths to the SOFA scene, mesh and outputs: +- The scene you want to work on +- The folder where you want the results to be put in + + +```python +# Select Output Dir and original scene name & path +from PyQt5 import QtWidgets +app = QtWidgets.QApplication(sys.argv) + +originalScene = utility.openFileName('Select the SOFA scene you want to reduce') +outputDir = utility.openDirName('Select the directory that will contain all the results') + +# If you haven't installed PyQt the previous function won't work +# As an alternative you can enter the absolute path to the corresponding files directly: +# originalScene = /PathToMy/Original/Scene +``` + +### 2. The different reduction parameters + +#### nodeToReduce + + + contains the SOFA path from the rootnode to the model you want to reduce. + + +```python +nodesToReduce_DIAMOND = ['/modelNode'] +nodesToReduce_STARFISH =['/model'] +``` + +#### listObjToAnimate + +Contains a list of objects from the class [ObjToAnimate](https://modelorderreduction.readthedocs.io/en/latest/_autosummary/_autosummary/_autosummary/mor.reduction.reduceModel.ObjToAnimate.html). + +An ObjToAnimate will define an object to "animate" during the shaking. + +There are 3 main parameters to this object : +- location: Path to obj/node we want to animate. +- animFct: the animation function we will use (here we use [defaultShaking](https://modelorderreduction.readthedocs.io/en/latest/_autosummary/_autosummary/mor.animation.defaultShaking.html)). +- all the arguments that will be passed to the animFct we have chosen. + +For example, here we want to animate the node named "north", but we won't specify the animFct so the default animation function will be used and applied to the first default object it will find. The default function will need 3 additional parameters : +- incrPeriod (float): Period between each increment +- incr (float): Value of each increment +- rangeOfAction (float): Until which value the data will increase + +north = ObjToAnimate("north", incr=5,incrPeriod=10,rangeOfAction=40) + + +```python +# animation parameters + +### CABLE-DRIVEN PARALLEL ROBOT PARAMETERS +north = ObjToAnimate("modelNode/north", incr=5,incrPeriod=10,rangeOfAction=40) +south = ObjToAnimate("modelNode/south", incr=5,incrPeriod=10,rangeOfAction=40) +east = ObjToAnimate("modelNode/east", incr=5,incrPeriod=10,rangeOfAction=40) +west = ObjToAnimate("modelNode/west", incr=5,incrPeriod=10,rangeOfAction=40) +listObjToAnimate_DIAMOND = [north,south,east,west] + +### MULTIGAIT SOFT ROBOT PARAMETERS +centerCavity = ObjToAnimate("model/centerCavity", incr=350,incrPeriod=2,rangeOfAction=3500) +rearLeftCavity = ObjToAnimate("model/rearLeftCavity", incr=200,incrPeriod=2,rangeOfAction=2000) +rearRightCavity = ObjToAnimate("model/rearRightCavity", incr=200,incrPeriod=2,rangeOfAction=2000) +frontLeftCavity = ObjToAnimate("model/frontLeftCavity", incr=200,incrPeriod=2,rangeOfAction=2000) +frontRightCavity = ObjToAnimate("model/frontRightCavity", incr=200,incrPeriod=2,rangeOfAction=2000) +listObjToAnimate_STARFISH = [centerCavity,rearLeftCavity,rearRightCavity,frontLeftCavity,frontRightCavity] +``` + +#### Modes parameters + +- addRigidBodyModes (Defines if our reduce model will be able to translate along the x, y , z directions) +- tolModes ( Defines the level of accuracy we want to select the reduced basis modes) + + +```python +addRigidBodyModes_DIAMOND = [0,0,0] +addRigidBodyModes_STARFISH = [1,1,1] + +tolModes = 0.001 +``` + +- tolGIE + + tolerance used in the greedy algorithm selecting the reduced integration domain(RID). Values are between 0 and 0.1 . High values will lead to RIDs with very few elements, while values approaching 0 will lead to large RIDs. Typically set to 0.05. + + +```python +# Tolerance +tolGIE = 0.05 +``` + +### 3 -- Optional parameters + + +```python +# Optionnal +verbose = False +nbrCPU = 4 +packageName = 'test' +addToLib = False +``` + +- verbose + + can bring more useful log while doing a reduction. + +- nbrCPU + + depending on the number of ObjToAnimate you have previously declared, the reduction process will need to launch many sofa scenes with different animation patterns. To do that faster we can parallelise this process by indicating a number of CPU and doing so the number of scenes that will be run simultaneously. + +- addToLib & packageName + + These 2 variables are to be used if you want at the end of the reduction to create a reusable python module of the result that will be placed in `/python/morlib` to import and use it easily in your scene. + + +We can now execute one of the reductions we choose with all these parameters + +## Execution + + +### Initialization + +The execution is done with an object from the class {py:class}`.ReduceModel`. +we initialize it with all the previous argument either for the Diamond or Starfish example + + +```python +# Initialization of our script +nodesToReduce = nodesToReduce_DIAMOND # nodesToReduce_STARFISH +listObjToAnimate = listObjToAnimate_DIAMOND # listObjToAnimate_STARFISH +addRigidBodyModes = addRigidBodyModes_DIAMOND # addRigidBodyModes_STARFISH + +reduceMyModel = ReduceModel( originalScene, + nodesToReduce, + listObjToAnimate, + tolModes,tolGIE, + outputDir, + packageName = packageName, + addToLib = addToLib, + verbose = verbose, + addRigidBodyModes = addRigidBodyModes) +``` + +We can finally perform the actual reduction. + +### {py:meth}`.phase1` + +We modify the original scene to do the first step of MOR : +- We add animation to each actuators we want for our model +- And add a writeState componant to save the shaking resulting states + + +```python +reduceMyModel.phase1() +``` + +### {py:meth}`.phase2` + +With the previous result we combine all the generated state files into one to be able to extract from it the different mode + + +```python +reduceMyModel.phase2() +``` + +```python +print("Maximum number of Modes : ") +reduceMyModel.reductionParam.nbrOfModes +``` + +### {py:meth}`.phase3` + +We launch again a set of sofa scene with the sofa launcher with the same previous arguments but with a different scene + +This scene take the previous one and add the model order reduction component: +- HyperReducedFEMForceField +- MechanicalMatrixMapperMOR +- ModelOrderReductionMapping and produce an Hyper Reduced description of the model + + +```python +reduceMyModel.phase3() +``` + +### {py:meth}`.phase4` + +Final step : we gather again all the results of the previous scenes into one and then compute the RID and Weigts with it. Additionnally we also compute the Active Nodes + + + +```python +reducedScene = reduceMyModel.phase4() +``` + +End of example you can now go test the results in the folder you have designed at the beginning of this tutorial + +## To go Further + +Links to additional information about the plugin: + +**[Publication in IEEE Transactions On Robotics](https://hal.inria.fr/hal-01834483)** + +**[Plugin website](https://project.inria.fr/modelorderreduction/)** + +**[Plugin doc](https://modelorderreduction.readthedocs.io/en/latest/index.html)** diff --git a/doc/sphinx/source/usage/principle/principle.rst b/doc/sphinx/source/usage/principle/principle.rst new file mode 100644 index 00000000..012ca836 --- /dev/null +++ b/doc/sphinx/source/usage/principle/principle.rst @@ -0,0 +1,4 @@ +.. toctree:: + :maxdepth: 2 + + reductionPrinciple diff --git a/doc/sphinx/source/usage/principle/reductionPrinciple.md b/doc/sphinx/source/usage/principle/reductionPrinciple.md new file mode 100644 index 00000000..52e3aca3 --- /dev/null +++ b/doc/sphinx/source/usage/principle/reductionPrinciple.md @@ -0,0 +1,9 @@ +# Reduction principles + +🚧 + +## get python scene +## perform shaking +## create reduce basis +## perform hyperreduction +## get reduced model