function e = e_measure ( dim_num, n, z, ns, sample_routine )

%*****************************************************************************80
%
%% e_measure() determines the pointset quality measure E.
%
%  Discussion:
%
%    The E measure of point distribution quality for a set Z of
%    N points in an DIM_NUM dimensional region is defined as follows:
%
%    Assign every point X in the region to the nearest element
%    Z(I) of the point set.  For each point Z(I), let E_VEC(I) be the
%    integral of the distance between Z(I) and all the points assigned to
%    it:
%
%      E_VEC(I) = Integral ( all X nearest to Z(I) ) distance ( X, Z(I) )
%
%    If we let VOLUME be the volume of the region, then we define E by:
%
%      E = sum ( 1 <= I <= N ) E_VEC(I) / VOLUME
%
%    This quantity can be estimated by using sampling to pick a large
%    number of points in the region, rather than all of them.
%
%    The E measure is minimized by a centroidal Voronoi tessellation.
%
%    Given two meshes, the one with a lower value of E is to be recommended.
%
%  Licensing:
%
%    This code is distributed under the MIT license.
%
%  Modified:
%
%    08 July 2021
%
%  Author:
%
%    John Burkardt
%
%  Reference:
%
%    Max Gunzburger, John Burkardt,
%    Uniformity Measures for Point Samples in Hypercubes.
%
%  Input:
%
%    integer DIM_NUM, the spatial dimension.
%
%    integer N, the number of points.
%
%    real Z(DIM_NUM,N), the points.
%
%    integer NS, the number of sample points.
%
%    character SAMPLE_ROUTINE, the name of the function to be used to
%    return sample points in the region.  The function must have the form
%      x = sample_routine ( dim_num, n )
%
%  Output:
%
%    real E, the E quality measure.
%
  e_vec(1:n) = 0.0;

  for k = 1 : ns

    x = feval ( sample_routine, 1, dim_num );

    closest = find_closest ( dim_num, n, 1, x, z );

    dist = sum ( ( x(1,1:dim_num) - z(closest(1),1:dim_num) ).^2 );

    e_vec(closest(1)) = e_vec(closest(1)) + dist;

  end

  e = sum ( e_vec(1:n) ) / ns;

  return
end
