Creating and handling the Voronoi geometry
The most basic thing is the creation of a list of Points. We advise to use the following:
HighVoronoi.VoronoiNodes
— MethodVoronoiNodes(x::Matrix)
also available in the forms
VoronoiNodes(x::Vector{<:Vector})
VoronoiNodes(x::Vector{<:SVector})
creates a list of points (as static vectors) from a matrix.
Example: 100 Points in $(0,1)^3$
data = rand(3,100)
points = VoronoiNodes(data)
The creation and storage of Voronoi geometry data is handled by the following class.
HighVoronoi.VoronoiGeometry
— TypeVoronoiGeometry{T}
This is the fundamental struct to store information about the generated Voronoi grid. The geometric data can be accessed using the type VoronoiData
. However, there is always the possibility to access the data also via the following fields:
- Integrator.Integral: stores the integrated values in terms of a
Voronoi_Integral
- basic_mesh: stores the fundamental data of nodes and verteces. also stored in Integrator.Integral.MESH
- nodes: direct reference to the nodes. Also provided in basic_mesh.nodes
Accessing the data directly, that is without calling VoronoiData
, is likely to cause confusion or to provide "wrong" information. The reason is that particularly for periodic boundary conditions, the mesh is enriched by a periodization of the boundary nodes. These nodes are lateron dropped by the VoronoiData-Algorithm.
To create a Voronoi mesh it is most convenient to call either of the following methods
HighVoronoi.VoronoiGeometry
— MethodVoronoiGeometry(xs::Points,b::Boundary)
This creates a Voronoi mesh from the points xs
given e.g. as an array of SVector
and a boundary b
that might be constructed using the commands in the Boundaries section.
You have the following optional commands:
integrator
: can be either one of the following values:VI_GEOMETRY
: Only the basic properties of the mesh are provided: the verteces implying a List of neighbors of each nodeVI_MONTECARLO
: Volumes, interface areas and integrals are calculated using a montecarlo algorithm. This particular integrator comes up with the following additional paramters:mc_accurate=(int1,int2,int3)
: Montecarlo integration takes place inint1
directions, overint2
volumetric samples (vor volume integrals only). It reuses the same set of directionsint3
-times to save memory allocation time. Standard setting is:(1000,100,20)
.
VI_POLYGON
: We use the polygon structure of the mesh to calculate the exact values of interface area and volume. The integral over functions is calculated using the values at the center, the verteces and linear interpolation between.VI_HEURISTIC
:
integrand
: This is a functionf(x)
depending on one spatial variablex
returning aVector{Float64}
. The integrated values will be provided for each cell and for each pair of neighbors, i.e. for each interfaceperiodic_grid
: This will initiate a special internal routine to fastly create a periodic grid. Look up the section in the documentation.
Advanced methods
VoronoiGeometry(file::String)
VoronoiGeometry(VG::VoronoiGeometry)
Loads a Voronoi mesh from the file
or copies it from the original data VG
. If integrator
is not provided, it will use the original integrator stored to the file. In the second case, if integrand is not provided explicitly, it will use integrand = VG.integrand
as standard. Additionally it has the following options:
_myopen=jldopen
: the method to use to open the file. See the section onwrite_jld
.offset
: See the section onwrite_jld
.integrate=false
: This will or will not call the integration method after loading/copying the data. Makes sense for usingVI_HEURISTIC
together withvolume=true
,area=true
and providing values forintegrand
andintegrand
. Ifintegrand != nothing
butbulk==false
orinterface==false
this parameter will internally be settrue
.volume=true
: Load volume data from filearea=true
: Load interface area data from filebulk=false
: Load integrated function values on the cell volumes from file. When settrue
andintegrand=f
is provided the method will compare the dimension off
and of the stored data.interface=false
: Load integrated function values on the interfaces. When settrue
andintegrand=f
is provided the method will compare the dimension off
and of the stored data.
Storage
HighVoronoi.write_jld
— MethodThe data can be stored using the write_jld
method:
write_jld(Geo::VoronoiGeometry,filename,offset="";_myopen=jldopen)
write_jld(Geo::VoronoiGeometry,file,offset="")
stores the complete information of a VoronoiGeometry object to a file. This information can later be retrieved using the VoronoiGeometry(file::String, args...)
function.
Geo
: The Voronoi geometry object to be storedfilename
: name of file to store infile
: A file given in a format supportingwrite(file,"tagname",content)
andread(file,"tagname",content)
offset
: If several Geometry objects are to be stored in the same file, this will be the possibility to identify each one by a unique name. In particular, this is the key to store several objects in one single file._myopen
: a method that allows the syntax_myopen(filename,"w") do myfile ....... end
. By default the method uses theJLD2
library as this (at the point of publishing this package) has the least problems with converting internal data structure to an output format.
If you want to use the default method, then the filename should end on .jld
. Otherwise there might be confusion by the abstract built in julia loading algorithm.
HighVoronoi.load_Voronoi_info
— MethodIf you want to make sure that the data you load will be rich enough, compact information can be retrieved as follows:
load_Voronoi_info(filname,offset="")
This will print out compact information of the data stored in file filename
and the offset offset
. Yields dimension, number of nodes, number of internal nodes and the dimension of the stored integrated data. Note that the latter information is of particular importance since here is the highest risk for the user to mess up stored data with the algorithm.
Extraction of VoronoiData
data for further processing
HighVoronoi.VoronoiData
— TypeUsing the call
data=VoronoiData(VG)
some data of the Voronoi geometry VG
is extracted. Once applied, the data set contains at least the following informations:
nodes::Vector{T}
: The original nodesneighbors::Vector{Vector{Int64}}
: For each nodenodes[i]
the fieldneighbors[i]
contains a sorted list of indeces of all neighboring cells. Multiple appearence of the same node is possible on a periodic grid.
Fields in VoronoiData
Conditionally on what the VoronoiGeometry
VG
was told to calculate, the set data
contains the following additional information:
volume::Vector{Float64}
: the volume for each nodearea::Vector{Vector{Float64}}
: stores for each neighborneighbors[i][k]
of nodei
inarea[i][k]
the area of the interface.bulk_integral::Vector{Vector{Float64}}
: the integral over the bulk functioninterface_integral::Vector{Vector{Vector{Float64}}}
: same as forarea
but with the integral values of the interface function. In paricularinterface_integral[i][k]
is of typeVector{Float64}
If the four above data fieds where not requested to be calculated, the vectors have length 0
and any attempt to access their values will eventually result in an error message.
Named Arguments
The call of VoronoiData(VG)
provides the following options:
view_only=false
: Iftrue
this implies that fornodes
,volume
,area
,bulk_integral
andinterface_integral
only views on the internally stored data will be provided. When set tofalse
, deep copies of the of the internal data will be provided.neighbors
will always be explicitly defined within this dataset only (i.e. noview
)reduce_to_periodic=true
: This erases all data generated from the periodization. It is highly advised to set this option totrue
as the user will then only see the periodic mesh as one would expect it.getorientations=false
: This is set automatically totrue
oncereduce_to_periodic==true
. Once settrue
the result contains the fieldorientations::Vector{Vector{T}}
,T
being the type of d-dimensional vectors originally provided by the nodes of the grid.getverteces=false
: Set totrue
the fieldverteces::Vector{Dict{Vector{Int64},T}}
will for each nodei
contain a dictionary[nodes]=>coordinate
. furthermore, the fieldboundary_verteces::Dict{Vector{Int64},boundary_vertex{T}}
will contain a list of edges that go to infinitygetboundarynodes=false
: Set totrue
the fieldboundary_nodes::Dict{Int64,Dict{Int64,T}}
will contain a dictionarynode=>Dict(boundary=>point)
, where boundary is the indexboundary = length(nodes) + number_of_boundary_plane
. Whenonboundary==false
thenpoint
will be mirrored version ofnodes[node]
at the boundary planenumber_of_boundary_plane
. Otherwise,point
is the center ofnodes[node]
and its mirrored versiononboundary=false
: Explained in the last topic. Furthermore, the value is stored inboundary_nodes_on_boundary::Bool
sorted=true
: During the reduction of the internal pseude periodic mesh to the fully periodic output, the neighbors (jointly with their respective properties) get sorted by their numbers