Performance-and-memory-optimization.md

@@ -6,15 +6,18 @@ Several techniques and good practices can help to improve the Structure builder
 
 ### Free objects not being used 
 
-(memory opt.) The Three.js library requires to explicitly free the resources not being used longer. In our case it's specially interesting to free the meshes making up a structure when we don't want to work on it longer (when we load other structure or reset the viewer).
+(memory opt.) The *Three.js* library [requires to explicitly free the resources](https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects) not being used longer. In our case it's specially interesting to free the meshes making up a structure when we don't want to work on it longer (when we load other structure or reset the viewer). This prevents from meaningful memory leaks that could lead the application to crash in long use sessions. 
 
-Textures adding up (looking at https://threejs.org/docs/#api/en/renderers/WebGLRenderer.info)
+We can use the *[WebGLRenderer.info](https://threejs.org/docs/#api/en/renderers/WebGLRenderer.info)* attribute to check the resources being help by the application. It seems that the geometries are being freed properly. I'm not so sure (`PENDING`) for the textures (this is less important because they take up far less memory)
 
-### Using more efficient Threejs data structures
+### Using more efficient *Threejs* data structures
 
 (memory and performance opt.) 
 Meaningful geometries like the ones representing atoms and bonds are switched to BufferGeometry versions: *SphereBufferGeometry* and *CylinderBufferGeometry* repectively.
 
+The impact on the memory use is spectacular: working with the Supercell (1300 atoms) the memory use goes from 
+850M (memory footprint) / 650M (javascript live memory) to  120M (memory footprint) / 42M (javascript live memory) 
+
 For more info: [BufferGeometry](https://threejs.org/docs/#api/en/core/BufferGeometry)
 
 ### Adapting the detail level of the atom geometry to the context
@@ -35,22 +38,17 @@ The percentages represent the final number of vertices relating to the initial o
 
 I've also reduce the *radialSegments* of bonds geometry but in this case the gain is small (the number of vertices per bond is smaller and fixed).
 
-The final implementation add a new variable (the size of the structure, number of atoms) to determine the segments number of the atoms geometry, this is the expression:
-`nSegments = 5 + Math.ceil(15*(1 - numAtoms/2500)*radius)`
-
-MEMORY results
-
-> First one is memory "reserved for JavaScript VM heap", the other one is "how much memory live (reachable) objects comprise" (source). When benchmarking your applications you should worry only about the second value, all the rest will be handled by GC. 
-
-24 segments 150M 42M live
-optimized 100-120M 42
-18 segments 115-120M 42live
-
-
+At the beginning seemed the vertices optimization will play an important role in order to reduce the memory use and I designed this optimization expression (good trade-off between geometry quality and number of vertices):
 
+`nSegments = 5 + Math.ceil(15*(1 - numAtoms/2500)*radius)`
 
+This adds a new variable (the size of the structure, number of atoms) to determine the segments number of the atoms geometry.
 
+But later once using the *BufferGeometry* versions of the primitives I realized the vertices optimizations is hardly worth it. Some figures (testing on the supercell - 1300 atoms):
 
+Fixed 24 segments per atom: 150M (memory footprint) / 42M (javascript live memory) 
+Optimized (above expression): 100-120M (memory footprint) / 42M (javascript live memory) 
+Fixed 18 segments per atom: 115-120M (memory footprint) / 42M (javascript live memory)
 
 
 ### Reusing object attributes (geometry, materials, etc) for atoms (species prototype atom for each species) and bonds