% addVoid - Create void regions inside 3-D geometry.
%
%   NewGM = addVoid(GM1,GM2) creates void regions inside one cell of the
%   geometry GM1 using all cells of the geometry GM2. All cells of geometry
%   GM2 must appear inside one cell of geometry GM1.
%   GM1 and GM2 are handles to 3-D geometry objects. NewGM is a handle
%   to the modified geometry object GM1.
%
%   NewGM = addVoid(GM1,GM2) adds all cells of geometry GM2 as a single
%   void region inside the cell of geometry GM1 within which they are
%   positioned.
%   GM2 is a handle to the 3-D geometry object. GM2 must be fully
%   encompassed within a single cell of GM1.
%   NewGM is a handle to the geometry object GM1.
%
%   Added void regions modify a geometry, but they do not modify the mesh.
%   After adding void regions, always call generateMesh. Creating a new
%   mesh ensures a proper mesh association with the new geometry.
%
%   Example: Add a cubical cavity inside another cube.
%
%       g1 = multicuboid(1,1,1);
%       g2 = multicuboid(0.5,0.5,0.5,'Zoffset',0.25);
%       newgm = addVoid(g1,g2);
%       pdegplot(newgm,'CellLabels','on','EdgeLabels','on','FaceAlpha',0.7);
%
%   See also pde.DiscreteGeometry, pde.EquationModel/importGeometry,
%            pde.DiscreteGeometry/addCell,
%            pde.EquationModel/generateMesh

% Copyright 2020 The MathWorks, Inc.
% Built-in function.
