Voronoi: Nodes and Geometry, Integrators

VoronoiNodes(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)

DensityRange{S}

provides a rectangular grid of points in a S-dimensional space. It is initialized as follows:

DensityRange(mr::AbstractVector{<:Integer},range)

Here, range can be of the following types:

• AbstractVector{Tuple{<:Real,<:Real}}: It is assumed that each entry of range is a tuple (a_i,b_i)

so the range is defined in the cuboid (a_1,b_1) imes... imes(a_{dim},b_{dim})

mr is assumed to have the same dimension as range and the interval (a_i,b_i) will be devided into mr[i] intervalls

• AbstractVector{<:Real}: if e.g. range=[1.0,1.0] this will be transferred to range=[(0.0,1.0),(0.0,1.0)]

and the first instance of the method is called

• Float64: range will be set range*ones(Float64,length(mr)) and the second instance is called
• Tuple{<:Real,<:Real}: range will be set to an array of identical tuple entries and the first version is called

Alternatively, one may call the following method:

DensityRange(mr::Int,range,dimension=length(range))

it is assumed that range is an array or tuple of correct length and mr is replaced by mr*ones(Int64,dimension). If range is not an array, then dimension has to be provided the correct value.

VoronoiGeometry{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

VoronoiGeometry(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:

• silence: Suppresses output to the command line when true. The latter will speed up the algorithm by a few percent. default is false.
• 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 node
  • VI_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 in int1 directions, over int2 volumetric samples (vor volume integrals only). It reuses the same set of directions int3-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: When this integrator is chosen, you need to provide a fully computed Geometry including volumes and interface areas. VI_HEURISTIC will then use this information to derive the integral values.
  • VI_HEURISTIC_MC: This combines directly VI_MONTECARLO calculations of volumes and interfaces and calculates integral values of functions based on those volumes and areas. In particular, it also relies on mc_accurate!
• integrand: This is a function f(x) depending on one spatial variable x returning a Vector{Float64}. The integrated values will be provided for each cell and for each pair of neighbors, i.e. for each interface
• periodic_grid: This will initiate a special internal routine to fastly create a periodic grid. Look up the section in the documentation.

With density distribution:

VoronoiGeometry(number::Int,b=Boundary();density, kwargs...)

this call genertates a distribution of approsximately number nodes and generates a VoronoiGeometry. It takes as parameters all of the above mentioned keywords (though periodic_grid makes no sense) and all keywords valid for a call of VoronoiNodes(number;domain=b,density=density, ....)

In future versions, there will be an implementation of the parameter cubic=true, where the grid will be generated based on a distribution of "cubic" cells. In the current version there will be a warning that this is not yet implemented.

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 on write_jld.
• vertex_storage: Defines the way data is stored internally. standard is the most recent and most efficient method DatabaseVertexStorage(). Other options are the ReferencedVertexStorage() which is slower but may be useful in low dimensions and the ClassicVertexStorage() which is fast for integration algorithms in low dimensions and which was the first database structure underlying the computations. This parameter can of course only be set upon the very first creation of the geometry and cannot be modified afterwards.
• search_settings: a NamedTuple mostly to provide (method = ... ,threading = ...) where method chooses the Raycast method and threading provides information on the multithreading
• offset: See the section on write_jld.
• integrate=false: This will or will not call the integration method after loading/copying the data. Makes sense for using VI_HEURISTIC together with volume=true, area=true and providing values for integrand and integrand. If integrand != nothing but bulk==false or interface==false this parameter will internally be set true.
• volume=true: Load volume data from file
• area=true: Load interface area data from file
• bulk=false: Load integrated function values on the cell volumes from file. When set true and integrand=f is provided the method will compare the dimension of f and of the stored data.
• interface=false: Load integrated function values on the interfaces. When set true and integrand=f is provided the method will compare the dimension of f and of the stored data.

The 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 stored
• filename: name of file to store in
• file: A file given in a format supporting write(file,"tagname",content) and read(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 the JLD2 library as this (at the point of publishing this package) has the least problems with converting internal data structure to an output format.

Using the call

data=VoronoiData(VG)

some data of the Voronoi geometry VG is extracted and presented to the user in a convenient way that requires no knowledge of the complicated multilevel data structures of VoronoiGeometry. Once applied, the data set contains at least the following informations:

• nodes::Vector{T}: The original nodes
• vertices: For each i this is an iterator over the vertices of cell i
• boundary_vertices: This is an iterator of the form edge => (base,direction,node) where edge is a list of generators of an infinite edge, base the start of the edge, direction the orientation and node is one additional generator that defines base together with edge.

Additional Fields in VoronoiData

The set data contains the following additional information, which is READ_ONLY in the standard setting. The standard read-only datastructures are highly involved as the output values are generated on-the-fly from internal data in order to save memory. See below to extract easier editable data structures

• neighbors: For each node nodes[i] the field neighbors[i] contains a sorted list of indeces of all neighboring cells. Multiple appearence of the same node is possible on a periodic grid.
• volume: the volume for each node
• area: stores for each neighbor neighbors[i][k] of node i in area[i][k] the area of the interface.
• bulk_integral: the integral over the bulk of each cell. bulk_integral[i] is of type AbstractVector{Float64}
• interface_integral: same as for area but with the integral values of the interface function. In paricular interface_integral[i][k] is of type AbstractVector{Float64}
• orientations: If the neighbors have been calculated by the integral algorithm, then for each neighbor[i][k] there is the matched orientation from i to k. This is particularly useful in periodic geometries, where manual calculation of this vector is tricky.
• boundary_nodes: A collection iterating as Tuple(generator_i,collection(boundary_index=>mirrored_generator)). In particular, if the cell of generator i touches the boundary then boundary_nodes has a key i. The value is a dictionary that has for every boudnary plane 'k' that is touched the mirrored version of generator i (if onboudary=false) or its projection onto plane k (if onboudary=true).
• offset: If reduce_to_periodic=false, this field will contain the number of internal nodes. The official nodes start from offset+1.
• references: If offset>0 then there exist a vectors references and reference_shifts of length(offset) stating that node[i]=node[references[i]]+reference_shifts[i] for i in 1:length(offset).
• reference_shifts: See the previous entry
• boundary: If reduce_to_periodic=false this contains the internal boundary that is used to compute the periodic structure. Otherwise this contains the official boundary of the domain.
• geometry: For internal use, this is a reference to VG.

Named Arguments

The call of VoronoiData(VG) provides the following options:

• getFIELD: replace FIELD with any of the above names except geometry to obtain a hard copy of the respective data that is detached from the internal data structure and can be modified or stored separately.
• copyall=true: corresponds to setting getFIELD=true for every FIELD.
• reduce_to_periodic=true: This hides all internal data generated from the periodization. It is highly advised to set this option to true as the user will then only see the periodic mesh with no information overhead.
• onboundary=false: refer to boundary_nodes above
• sorted=true: During the reduction of the internal pseudo periodic mesh to the fully periodic output, the neighbors (jointly with their respective properties) get sorted by their numbers. This is only possible if getarea,getneighbors and getinterfaceintegral are true. Otherwise it will be ignored