Refactoring (#30)

* readdata --> load

* Use Symbol for internal file type representation; add length of meta data; remove @require for Plots

* Clean up tag related comments

* filename -> file

.vscode/settings.json

@@ -0,0 +1 @@
+{}

README.md

@@ -9,11 +9,12 @@
 Fast [BATSRUS](https://github.com/MSTEM-QUDA/BATSRUS)/[SWMF](https://github.com/MSTEM-QUDA/SWMF) data reading, converting, and visualizing using Julia, successor of [VisAnaMatlab](https://github.com/henry2004y/VisAnaMatlab).
 
 This package provides the following functionalities:
-  * simulation data reader
-  * 2D/3D region cut from the whole domain
-  * interpolation from unstructured to structured data
-  * data format conversion to VTK
-  * simulation data visualization through multiple plotting libraries
+
+* simulation data reader
+* 2D/3D region cut from the whole domain
+* interpolation from unstructured to structured data
+* data format conversion to VTK
+* simulation data visualization through multiple plotting libraries
 
 For more details, please check the [document][Batsrus-doc].
 
@@ -24,7 +25,8 @@ For more details, please check the [document][Batsrus-doc].
 * (Optional) Python and Matplotlib
 
 ## Installation
-```
+
+```julia
 using Pkg
 Pkg.add("Batsrus")
 ```
@@ -37,12 +39,14 @@ See the [examples](https://henry2004y.github.io/Batsrus.jl/dev/man/examples/).
 
 In Python, you can easily take advantage of this package with the aid of [PyJulia](https://pyjulia.readthedocs.io/en/latest/).
 After the installation, in the Python repl:
+
 ```python
 from julia import Batsrus
 dir = 'test'
-filename = '1d__raw_2_t25.60000_n00000258.out'
-data = Batsrus.readdata(filename, dir=dir)
+file = '1d__raw_2_t25.60000_n00000258.out'
+data = Batsrus.load(file, dir=dir)
 ```
+
 There you have it! Enjoy!
 
 ## Benchmark
@@ -53,10 +57,6 @@ See the [benchmark](https://henry2004y.github.io/Batsrus.jl/dev/#Benchmark-1) in
 
 * **Hongyang Zhou** - *Initial work* - [henry2004y](https://github.com/henry2004y)
 
-## Acknowledgments
-
-* All the nice guys who share their codes!
-
 [codecov-img]: https://codecov.io/gh/henry2004y/Batsrus.jl/branch/master/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/henry2004y/Batsrus.jl
 [Batsrus-doc]: https://henry2004y.github.io/Batsrus.jl/dev

docs/src/index.md

@@ -8,27 +8,31 @@
 [BATSRUS](https://github.com/MSTEM-QUDA/BATSRUS) and [SWMF](https://github.com/MSTEM-QUDA/SWMF) data reading, converting, visualizing and analyzing in Julia.
 
 This package provides the following functionalities:
-  * simulation data reader
-  * run log plots
-  * 2D/3D region cut from the whole data
-  * phase space distribution plots
-  * interpolation from unstructured to structured data
-  * data format conversion to VTK
-  * simulation data visualization
+
+* simulation data reader
+* run log plots
+* 2D/3D region cut from the whole data
+* phase space distribution plots
+* interpolation from unstructured to structured data
+* data format conversion to VTK
+* simulation data visualization
 
 The ultimate goal is to build a convenient tool of reading and analyzing simulation outputs which is easy to install and easy to use.
 
 !!! tip "Ready to use?"
     Feel free to contact the author for any help or collaboration!
 
 ## Installation
+
 Install VisAna from the `julia REPL` prompt with
+
 ```julia
 using Pkg
 Pkg.add("Batsrus")
 ```
 
 Or in the Pkg REPL
+
 ```julia
 julia> ]
 pkg> add Batsrus
@@ -66,12 +70,14 @@ For dynamic languages with JIT, the first time when function gets executed is al
 
 In Python, you can easily take advantage of this package with the aid of [PyJulia](https://pyjulia.readthedocs.io/en/latest/).
 After the installation, in the Python REPL:
+
 ```python
 from julia import Batsrus
 dir = 'test'
-filename = '1d__raw_2_t25.60000_n00000258.out'
-data = Batsrus.readdata(filename, dir=dir)
+file = '1d__raw_2_t25.60000_n00000258.out'
+data = Batsrus.load(file, dir=dir)
 ```
+
 There you have it! Enjoy!
 
 !!! warning "Python dependency"
@@ -82,3 +88,7 @@ There you have it! Enjoy!
 This package inherits the ideas and code structures from its predecessor in [IDL](https://github.com/MSTEM-QUDA/share/tree/stable/IDL) (developed by Gábor Tóth) and [MATLAB](https://github.com/henry2004y/VisAnaMatlab).
 
 Batsrus.jl is developed and maintained by [Hongyang Zhou](https://github.com/henry2004y).
+
+## Acknowledgments
+
+* All the nice guys who share their codes!

docs/src/man/examples.md

@@ -3,51 +3,59 @@
 ## IDL format output loader
 
 - Read data
+
 ```julia
-filename = "1d_bin.out";
-data = readdata(filename);
-data = readdata(filename, verbose=true);
-data = readdata(filename, npict=1);
-data = readdata(filename, dir=".");
+file = "1d_bin.out";
+data = load(file);
+data = load(file, verbose=true);
+data = load(file, npict=1);
+data = load(file, dir=".");
 ```
 
 - 3D structured spherical coordinates
+
 ```julia
-filename = "3d_structured.out";
-data = readdata(filename, verbose=false);
+file = "3d_structured.out";
+data = load(file, verbose=false);
 ```
 
 - log file
+
 ```julia
 logfilename = "shocktube.log";
 head, data = readlogdata(logfilename)
 ```
 
 ## Derived variables
+
 ```julia
 v = getvars(data, ["Bx", "By", "Bz"])
 B = @. sqrt(v["Bx"]^2 + v["By"]^2 + v["Bz"]^2)
 ```
 
 ## Output format conversion
+
 We can convert 2D/3D BATSRUS outputs `*.dat` to VTK formats. It uses the VTK XML format writer [writeVTK](https://github.com/jipolanco/WriteVTK.jl) to generate files for Paraview and Tecplot. The default converted filename is `out.vtu`.
 
 ASCII Tecplot file (supports both `tec` and `tcp`) and binary Tecplot file (set `DOSAVETECBINARY=TRUE` in BATSRUS `PARAM.in`):
+
 ```julia
-filename = "x=0_mhd_1_n00000050.dat"
-#filename = "3d_ascii.dat"
-#filename = "3d_bin.dat"
-head, data, connectivity = readtecdata(filename)
+file = "x=0_mhd_1_n00000050.dat"
+#file = "3d_ascii.dat"
+#file = "3d_bin.dat"
+head, data, connectivity = readtecdata(file)
 convertTECtoVTU(head, data, connectivity)
 ```
 
 3D structured IDL file (`gridType=1` returns rectilinear `vtr` file, `gridType=2` returns structured `vts` file):
+
 ```julia
-filename = "3d_structured.out"
-convertIDLtoVTK(filename, gridType=1)
+file3d_structured.out"
+convertIDLtoVTK(file, gridType=1)
 ```
 
 3D unstructured IDL file together with header and tree file:
+
 ```julia
 filetag = "3d_var_1_n00002500"
 convertIDLtoVTK(filetag)
@@ -57,6 +65,7 @@ convertIDLtoVTK(filetag)
     The file suffix should not be provided for this to work correctly!
 
 Multiple files:
+
 ```julia
 using Batsrus, Glob
 filenamesIn = "3d*.dat"
@@ -71,6 +80,7 @@ end
 ```
 
 If each individual file size is large, consider using:
+
 ```julia
 using Batsrus, Glob
 filenamesIn = "3d*.dat"
@@ -85,6 +95,7 @@ end
 ```
 
 Multiple files in parallel:
+
 ```julia
 using Distributed
 @everywhere using Batsrus, Glob
@@ -109,6 +120,7 @@ More examples can be found in [examples](https://github.com/henry2004y/Batsrus.j
 We provide plot recipes for Plots.jl and wrappers for PyPlot.jl.
 
 The recipes for Plots.jl will work on all functions given the correct dimensions, e.g.
+
 ```julia
 using Plots
 plot(data, "p")
@@ -126,12 +138,14 @@ Check out the documentation for more details.
 A general `plotdata` function is provided for quick visualizations using Matplotlib.
 
 - 1D binary
+
 ```julia
 plotdata(data, "p", plotmode="line")
 plotdata(data, "p", plotmode="linegrid")
 ```
 
 - 2D Cartesian (structured)
+
 ```julia
 plotdata(data, "p bx;by", plotmode="contbar streamover")
 plotdata(data, "p bx;by", plotmode="contbar quiverover")
@@ -144,18 +158,21 @@ plotdata(data, "p", plotmode="surfbar")
 ```
 
 - 2D unstructured
+
 ```julia
 plotdata(data, "rho", plotmode="contbar")
 plotdata(data, "rho", plotmode="trimesh")
 plotdata(data, "rho", plotmode="tricont")
 ```
 
 - 2D structured spherical coordinates
+
 ```julia
 plotdata(data, "rho", plotmode="contbar")
 ```
 
 - 3D box
+
 ```julia
 plotdata(data, "bx", plotmode="contbar", dir="y", sequence=1, level=20)
 plotdata(data, "bx", plotmode="contbar", dir="y", plotrange=[-1.4,-1.1,0.70,0.78])
@@ -169,6 +186,7 @@ cutplot(data, "Ex"; dir="y", sequence=128, plotrange)
 #### Finding indexes
 
 To get the index of a certain quantity, e.g. electron number density
+
 ```julia
 ρe_= findfirst(x->x=="rhoS0", data.head.wnames)
 ```
@@ -180,61 +198,71 @@ Some plotting functions can be directly called as shown below, which allows for
 `using PyPlot` to import the full capability of the package, etc. adding colorbar, changing line colors, setting colorbar range with `clim`.
 
 - line plot
+
 ```julia
 plot(data, "p", linewidth=2, color="green")
 c = plot(data, "p")
 plt.setp(c, linestyle="--", linewidth=2);
 ```
 
 - scatter plot
+
 ```julia
 scatter(data, "p")
 ```
 
 - contour
+
 ```julia
 # 2D contour
 contour(data, "p")
 ```
 
 - filled contour
+
 ```julia
 contourf(data, "p")
 contourf(data, "p", levels, plotrange=[-10,10,-Inf,Inf], plotinterval=0.1)
 ```
 
 - surface plot
+
 ```julia
 plot_surface(data, "p")
 ```
 
 - triangle surface plot
+
 ```julia
 plot_trisurf(data, "p")
 ```
 
 - triangle filled contour plot
+
 ```julia
 tricontourf(data, "p")
 ```
 
 - streamline
+
 ```julia
 streamplot(data, "bx;bz")
 streamplot(data, "bx;bz", density=2.0, color="k", plotinterval=1.0, plotrange=[-10,10,-Inf,Inf])
 ```
 
 - quiver (currently only for Cartesian grid)
+
 ```julia
 quiver(data, "ux;uy", stride=50)
 ```
 
 - streamline + contourf
+
 ```julia
 using Batsrus, PyPlot
 
-filename = "y*out"
-data = readdata(filename)
+file = "y*out"
+data = load(file)
 
 DN = matplotlib.colors.DivergingNorm
 set_cmap("RdBu_r")
@@ -255,11 +283,12 @@ xlabel("x"); ylabel("y"); title("uxS0")
 The built-in `streamplot` function in Matplotlib is not satisfactory for accurately tracing. Instead we recommend [FieldTracer.jl](https://github.com/henry2004y/FieldTracer.jl) for tracing fieldlines and streamlines.
 
 An example of tracing in a 2D cut and plot the field lines over contour:
+
 ```julia
 using Batsrus, PyPlot
 
-filename = "y=0_var_1_t00000000_n00000000.out"
-data = readdata(filename, dir="test")
+file = "y=0_var_1_t00000000_n00000000.out"
+data = load(file, dir="test")
 
 bx = data.w[:,:,5]
 bz = data.w[:,:,7]

docs/src/man/log.md

@@ -8,6 +8,7 @@ For the plotting, streamline tracing and particle tracing, a common problem is t
 ## Test Data
 
 If you don't have SWMF data at hand, Batsrus.jl provides some test data for you to begin with.
+
 ```julia
 using LazyArtifacts
 
@@ -19,12 +20,14 @@ These are also used in the standard test. These will be automatically downloaded
 ## VTK AMR Grid Structure
 
 `vtkOverlappingAMR` implements a somewhat strict Berger-Collela AMR scheme:
+
 1. All grids are Cartesian.
 2. Grids at the same level do not overlap.
 3. The refinement ratios, RL, between adjacent levels are integer (typically 2 or 4) and uniform within the same level.
 4. Grid cells are never partially refined; i.e., each cell is refined to four quads in 2D or eight hexahedra in 3D.
 
 Or in other words,
+
 * Refinement ratio across levels is constant.
 * Each block at levels > 0 need to be covered 100% by one parent block of
 previous level.
@@ -36,6 +39,7 @@ be any specialized filters such as the dual-grid contour / clip ones for
 the `vtkOverlappingAMR`.
 
 The `vtkAMRInformation` documentation consists only of
+
 * Refinement ratio between AMR levels
 * Grid spacing for each level
 * The file block index for each block parent child information, if requested