More consistent function APIs; improve docs

Project.toml

@@ -1,7 +1,7 @@
 name = "Batsrus"
 uuid = "e74ebddf-6ac1-4047-a0e5-c32c99e57753"
 authors = ["Hongyang Zhou <[email protected]>"]
-version = "0.2.7"
+version = "0.2.8"
 
 [deps]
 FortranFiles = "c58ffaec-ab22-586d-bfc5-781a99fd0b10"

src/io.jl

@@ -21,10 +21,10 @@ function Base.show(io::IO, s::Data)
 end
 
 """
-	readdata(filenameIn, (, dir=".", npict=1, verbose=false))
+	readdata(filenameIn; dir=".", npict=1, verbose=false)
 
 Read data from BATSRUS output files. Stores the `npict` snapshot from an ascii
-or binary data file into the coordinates `x` and data `w` arrays.
+or binary data file into the arrays of coordinates `x` and data `w`.
 Filenames can be provided with wildcards.
 
 # Examples
@@ -83,11 +83,11 @@ function readdata(filenameIn::AbstractString; dir=".", npict=1, verbose=false)
 
    verbose && @info "Finished reading $(filelist.name)"
 
-   return data
+   data
 end
 
 "Read information from log file."
-function readlogdata( filename::AbstractString )
+function readlogdata(filename::AbstractString)
 
    f = open(filename, "r")
    nLine = countlines(f) - 2
@@ -112,11 +112,11 @@ function readlogdata( filename::AbstractString )
    head = (ndim=ndim, headline=headline, it=it, time=t, gencoord=gencoord,
       nw=nw, nx=nx, variables=variables)
 
-   return head, data
+   head, data
 end
 
 """
-	readtecdata(filename, verbose=false)
+	readtecdata(filename; verbose=false)
 
 Return header, data and connectivity from BATSRUS Tecplot outputs. Both 2D and
 3D binary and ASCII formats are supported.
@@ -250,7 +250,7 @@ function readtecdata(filename::AbstractString; verbose=false)
    head = (variables=VARS, nNode=nNode, nCell=nCell, nDim=nDim, ET=ET,
 		title=title, auxdataname=auxdataname, auxdata=auxdata)
 
-   return head, data, connectivity
+   head, data, connectivity
 end
 
 
@@ -302,7 +302,7 @@ function getfiletype(filename)
 
    filelist = FileList(filename, type, bytes, npictinfiles)
 
-   return filelist, fileID, pictsize
+   filelist, fileID, pictsize
 end
 
 """
@@ -384,11 +384,11 @@ function getfilehead(fileID::IOStream, type::String)
 end
 
 function skipline(s::IO)
-    while !eof(s)
-        c = read(s, Char)
-        c == '\n' && break
-    end
-    return nothing
+   while !eof(s)
+       c = read(s, Char)
+       c == '\n' && break
+   end
+   nothing
 end
 
 "Return the size in bytes for one snapshot."
@@ -451,7 +451,7 @@ function getfilesize(fileID::IOStream, type::String)
       pictsize = headlen + 8*(1+nw) + 8*(ndim+nw)*nxs
    end
 
-   return pictsize
+   pictsize
 end
 
 
@@ -472,7 +472,7 @@ function allocateBuffer(filehead::NamedTuple, T::DataType)
       w  = Array{T,4}(undef,n1,n2,n3,filehead.nw)
    end
 
-   return x, w
+   x, w
 end
 
 "Read ascii format data."
@@ -501,7 +501,7 @@ function getascii!(x, w, fileID::IOStream, filehead::NamedTuple)
       end
    end
 
-   return nothing
+   nothing
 end
 
 
@@ -535,7 +535,7 @@ function getbinary!(x, w, fileID::IOStream, filehead::NamedTuple, T::DataType)
       end
    end
 
-   return nothing
+   nothing
 end
 
 """
@@ -746,7 +746,7 @@ function setunits( filehead::NamedTuple, type::AbstractString; distunit=1.0,
       di0  = cSI/(op0/tSI)/xSI                 # di=c/omegap = di0/sqrt(rho)
       ld0  = moq*√(pSI)/rhoSI/xSI              # ld          = ld0*sqrt(p)/rho
    end
-
+   nothing
 end
 
 """

src/select.jl

@@ -1,4 +1,4 @@
-export get_vars, cutdata, subvolume, subsurface
+export getvars, getvar, cutdata, subvolume, subsurface
 
 
 """
@@ -38,15 +38,14 @@ function cutdata(data::Data, var::AbstractString;
       cut1, cut2, W = subsurface(cut1, cut2, W, plotrange)
    end
 
-   return cut1, cut2, W
+   cut1, cut2, W
 end
 
 """
 	subsurface(x, y, data, limits)
 	subsurface(x, y, u, v, limits)
 
-Extract subset of 2D surface dataset.
-This is a simplified version of subvolume.
+Extract subset of 2D surface dataset. See also: [`subvolume`](@ref).
 """
 function subsurface(x, y, data, limits)
 
@@ -76,7 +75,7 @@ function subsurface(x, y, data, limits)
    newx = x[xind, yind]
    newy = y[xind, yind]
 
-   return newx, newy, newdata
+   newx, newy, newdata
 end
 
 function subsurface(x, y, u, v, limits)
@@ -108,14 +107,14 @@ function subsurface(x, y, u, v, limits)
    newx = x[xind, yind]
    newy = y[xind, yind]
 
-   return newx, newy, newu, newv
+   newx, newy, newu, newv
 end
 
 """
 	subvolume(x, y, z, data, limits)
 	subvolume(x, y, z, u, v, w, limits)
 
-Extract subset of 3D dataset in ndgrid format.
+Extract subset of 3D dataset in ndgrid format. See also: [`subsurface`](@ref).
 """
 function subvolume(x, y, z, data, limits)
    if length(limits)!=6
@@ -149,7 +148,7 @@ function subvolume(x, y, z, data, limits)
    newy = y[xind,yind,zind]
    newz = z[xind,yind,zind]
 
-   return newx, newy, newz, newdata
+   newx, newy, newz, newdata
 end
 
 function subvolume(x, y, z, u, v, w, limits)
@@ -186,7 +185,7 @@ function subvolume(x, y, z, u, v, w, limits)
    newy = y[xind,yind,zind]
    newz = z[xind,yind,zind]
 
-   return newx, newy, newz, newu, newv, neww
+   newx, newy, newz, newu, newv, neww
 end
 
 """
@@ -203,7 +202,7 @@ function subdata(data, xind::Vector{Int}, yind::Vector{Int}, sz::Tuple{Int,Int})
       newdata = reshape(newdata, (newsz[1:2]..., sz[3:end]))
    end
 
-   return newdata
+   newdata
 end
 
 function subdata(data, xind::Vector{Int}, yind::Vector{Int}, zind::Vector{Int},
@@ -216,11 +215,11 @@ function subdata(data, xind::Vector{Int}, yind::Vector{Int}, zind::Vector{Int},
       newdata = reshape(newdata, (newsz[1:3]..., sz[4:end]))
    end
 
-   return newdata
+   newdata
 end
 
-
-function get_var(data::Data, var::T) where T<:AbstractString	
+"Return variable data from string `var`."
+function getvar(data::Data, var::T) where T<:AbstractString	
    VarIndex_ = findfirst(x->x==lowercase(var), lowercase.(data.head.wnames))
    isnothing(VarIndex_) && error("$(var) not found in file header variables!")
 
@@ -235,12 +234,12 @@ function get_var(data::Data, var::T) where T<:AbstractString
    w
 end
 
-"Return data from input string vector."
-function get_vars(data::Data, Names::Vector{T}) where T<:AbstractString
+"Return variables' data from string vector. See also: [`getvar`](@ref)"
+function getvars(data::Data, Names::Vector{T}) where T<:AbstractString
 
    dict = Dict()
    for name in Names
-      dict[name] = get_var(data, name)
+      dict[name] = getvar(data, name)
    end
 
    Vars(dict)
@@ -250,9 +249,9 @@ Base.getproperty(p::Vars, name::Symbol) = getfield(p, :data)[String(name)]
 
 
 const variables_predefined = Dict(
-   "B" => data -> sqrt.(get_var(data, "Bx").^2 .+ get_var(data, "By").^2 .+ get_var(data, "Bz").^2),
-   "E" => data -> sqrt.(get_var(data, "Ex").^2 .+ get_var(data, "Ey").^2 .+ get_var(data, "Ez").^2),
-   "U" => data -> sqrt.(get_var(data, "Ux").^2 .+ get_var(data, "Uy").^2 .+ get_var(data, "Uz").^2),
-   #"beta" => data -> get_var(data, "P") ./ get_var(data, "B").^2 * 2μ,
+   "B" => data -> sqrt.(getvar(data, "Bx").^2 .+ getvar(data, "By").^2 .+ getvar(data, "Bz").^2),
+   "E" => data -> sqrt.(getvar(data, "Ex").^2 .+ getvar(data, "Ey").^2 .+ getvar(data, "Ez").^2),
+   "U" => data -> sqrt.(getvar(data, "Ux").^2 .+ getvar(data, "Uy").^2 .+ getvar(data, "Uz").^2),
+   #"beta" => data -> getvar(data, "P") ./ getvar(data, "B").^2 * 2μ,
 )
 

test/runtests.jl

@@ -52,7 +52,7 @@ end
       X, Z, p = cutdata(data, "p", cut='y', cutPlaneIndex=1, plotrange=plotrange)
       @test p[1] ≈ 0.560976f0
       @test p[2] ≈ 0.53704995f0
-      vars = get_vars(data, ["p"]) 
+      vars = getvars(data, ["p"]) 
       @test size(vars.p) == (8,8,8) 
    end