MRAMeshOrbitalPlot3D: better dox+usability (i.e., thicker default edg…

…es for the mesh cuboids)

src/madness/mra/tools/MRAMeshOrbitalPlot3D.wl

@@ -3,7 +3,18 @@
 BeginPackage["MRAMeshOrbitalPlot3D`"]
 
 
-MRAMeshOrbitalPlot3D::usage="MRAMeshOrbitalPlot3D[fp,opts] returns a plot of the orbital stored via madness::plot_cubefile and madness::print_json_treefile in files fp.cube and fp.tree.json, respectively. Option Zoom->x can be used to produce a plot in a zoomed-in section of the simulation cell. This does not need to match the zoom value given to plot_cubefile (that only affects the resolution/extent of the Gaussian Cube mesh)."
+(* ::Text:: *)
+(*{*)
+(* {Description: MRAMeshOrbitalPlot3D[fp,opts] returns a plot of the orbital stored via madness::plot_cubefile and madness::print_json_treefile in files fp . cube and fp . tree . json, respectively . MRAMeshOrbitalPlot3D accepts all options recognized by Graphics3D and ListContourPlot3D functions, as well as the following additional options:, \[SpanFromLeft], \[SpanFromLeft]},*)
+(* {Option, Default, Description},*)
+(* {Zoom, 1, can be used to produce a plot in a zoomed-in section of the simulation cell . This does not need to match the zoom value given to plot_cubefile (that only affects the resolution/extent of the Gaussian Cube mesh)},*)
+(* {MRAMeshCuboidDirectives, {EdgeForm[Thick]}, Specifies how the Cuboid objects comprising the MRA mesh are drawn . All Graphics3D directives that are applicable to Cuboid (except Opacity) can be specified . },*)
+(* {MaxLevel, Infinity, Controls the highest refinement level of displayed mesh elements .},*)
+(* {MinLevel, 0, Controls the lowest refinement level of displayed mesh elements .}*)
+(*}*)
+
+
+MRAMeshOrbitalPlot3D::usage="MRAMeshOrbitalPlot3D[fp,opts] returns a plot of the orbital stored via madness::plot_cubefile and madness::print_json_treefile in files fp.cube and fp.tree.json, respectively. MRAMeshOrbitalPlot3D accepts all options recognized by Graphics3D and ListContourPlot3D functions, as well as the following additional options: Zoom, MRAMeshCuboidDirectives, MinLevel, and MaxLevel."
 
 
 Begin["`Private`"]
@@ -38,19 +49,20 @@ BoxToXYZCoords[cell_, box_] :=
 
 BoxToGraphics[cell_, box_, nmax_, omax_(* opacity value of the smallest
      boxes *), shadeexp_(* opacity of box at level n-1 is this times smaller
-     than than of box at level n *)] :=
+     than than of box at level n *),cuboidDirectives_List] :=
     Module[{},
-        Return[{Opacity[omax / shadeexp ^ (nmax - box[[1]])], Cuboid 
-            @@ BoxToXYZCoords[cell, box]}]
+        Return[Join[(*N.B. MUST BE FIRST to apply to Cuboid*)cuboidDirectives,{Opacity[omax / shadeexp ^ (nmax - box[[1]])], Cuboid 
+            @@ BoxToXYZCoords[cell, box],EdgeForm[Thick]}]]
     ];
 
 (*
 MaxLevel,MinLevel: show boxes with resolution level [nmin,nmax]
 Zoom: limit PlotRange to cell/Zoom
 *)
 
+Protect[MaxLevel,MinLevel,Zoom,MRAMeshCuboidDirectives];
 Options[MRAMeshOrbitalPlot3D] = {MaxLevel -> Infinity, MinLevel -> 0, Zoom
-     -> 1};
+     -> 1,MRAMeshCuboidDirectives->{EdgeForm[Thick]}};
 
 (* plots orbital and its mesh superimposed *)
 
@@ -59,17 +71,20 @@ MRAMeshOrbitalPlot3D[filePrefix_, opt : OptionsPattern[{MRAMeshOrbitalPlot3D,
     Module[
         {simulationCell, boxTreeCoords, bohr2angstrom, selectedBoxes,
              boxGraphics, meshPlot, orbitalPlot, nmax, nmin, zoom, omax, shadeexp,
-             actualNMax, plotRange}
+             actualNMax,cuboidDirectives, plotRange}
         ,
         (* process options *)
         nmax = OptionValue[MaxLevel];
         nmin = OptionValue[MinLevel];
         zoom = OptionValue[Zoom];
+        cuboidDirectives=OptionValue[MRAMeshCuboidDirectives];
+
         (* these are hardwired since they are not needed for most users
              *)
         omax = 0;(* opacity value of the smallest boxes *)
         shadeexp = 1.9;(* opacity of box at level n-1 is this times smaller
              than than of box at level n *)
+
         {simulationCell, boxTreeCoords} = ReadTree[filePrefix <> ".tree.json"
             ]; (* the deduced hardwired value used by Wolfram when importing Gaussian
              Cube file *) bohr2angstrom = 0.529177249;
@@ -85,7 +100,7 @@ MRAMeshOrbitalPlot3D[filePrefix_, opt : OptionsPattern[{MRAMeshOrbitalPlot3D,
              >= nmin&];
         actualNMax = MaximalBy[selectedBoxes, #[[1]]&][[1, 1]];
         boxGraphics = Map[BoxToGraphics[simulationCell, #, actualNMax,
-             omax, shadeexp]&, selectedBoxes];
+             omax, shadeexp, cuboidDirectives]&, selectedBoxes];
         meshPlot = Graphics3D[boxGraphics, Boxed -> False, Evaluate @
              FilterRules[{opt}, Options[Graphics3D]]];
         orbitalPlot = Import[filePrefix <> ".cube", "Graphics3D", Boxed
@@ -96,6 +111,7 @@ MRAMeshOrbitalPlot3D[filePrefix_, opt : OptionsPattern[{MRAMeshOrbitalPlot3D,
     ];
 
 
+
 End[]
 
 

src/madness/mra/tools/README.md

@@ -7,7 +7,7 @@ This directory contains various utilities:
 - quadrature.py can be easily modified to generate the full-precision Gauss-Legendre coeffs
 - MRAMeshOrbitalPlot3D.wl ... a Wolfram language ("Mathematica", for the old school) package for plotting orbitals stored in the Gaussian Cube format (see `madness::plot_cubefile`) along with the mesh stored a JSON format (see `madness::print_tree_jsonfile`).
 
-## MRAMeshOrbitalPlot3D.wl
+## `MRAMeshOrbitalPlot3D.wl`
 
 - if you have [https://www.wolfram.com/wolframscript/](WolframScript) installed (yes by default on Windows/Linux; on a Mac need to [https://www.wolfram.com/wolframscript/](download/install manually)) to plot from command-line or shell script. See a quick example in `h2-no1.wsl`; to try out execute `./h2-no1.wsl > h2-no1.pdf` 
 - more elaborate plotting is best done from a Mathematica notebook. Here's a brief example:
@@ -17,3 +17,15 @@ This directory contains various utilities:
 (* this assumes that data.cube (produced by madness::plot_cubefile) and data.tree.json (produced by madness::print_tree_jsonfile) exist in /path/to/data
 MRAMeshOrbitalPlot3D["/path/to/data"]
 ```
+
+### 
+The only function `MRAMeshOrbitalPlot3D.wl` provides is `MRAMeshOrbitalPlot3D`.  `MRAMeshOrbitalPlot3D[fp,opts]` returns a plot of the orbital stored via `madness::plot_cubefile` and `madness::print_json_treefile` in files `fp.cube` and `fp.tree.json`, respectively. `MRAMeshOrbitalPlot3D` accepts all options recognized by `Graphics3D` and `ListContourPlot3D` functions, as well as the following additional options:
+
+| Option                      | Default             | Description                                                                                                                                                                                                        |
+|-----------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Zoom`                      | `1`                 | Can be used to produce a plot in a zoomed-in section of the simulation cell. This does not need to match the zoom value given to plot_cubefile (that only affects the resolution/extent of the Gaussian Cube mesh) |
+| `MRAMeshCuboidDirectives`   | `{EdgeForm[Thick]}` | Specifies how the Cuboid objects comprising the MRA mesh are drawn. All Graphics3D directives that are applicable to Cuboid (except Opacity) can be specified.                                                     |
+| `MaxLevel`                  | `Infinity`          | Controls the highest refinement level of displayed mesh elements.                                                                                                                                                  |
+| `MinLevel`                  | `0`                 | Controls the lowest refinement level of displayed mesh elements.                                                                                                                                                   |
+
+