Difference between revisions of "MPM Region and Hole Commands"

Latest revision as of 17:17, 26 April 2024

In MPM, the most common way to discretize an object is to add material points to the background grid using Region commands and to designate regions of the grid has having no material points using Hole commands. Enclosed in these commands are various shape commands to define the object. An alternative and powerful option for discretizing an object is to create material points automatically from an image of the object.

When modeling with membrane materials (which are only in OSParticulas), membrane material points are added with <Membrane> XML elements.

Region Commands

Once the background grid is created, material points are added to the grid using a series of Region commands. In scripted files, the Region command defines material type, initial velocity, thickness (in 2D), and optionally an initial angle (for some anisotropic materials), temperature, and concentration. The command is

Region (matid),(velx),(vely),(velz) or (thick),<(property),(value)>...
  (an initial angular velocity command)
  (any number of shape commands)
  (one optional Transform Command)
  (interspersed rotation commands)
EndRegion

In XML files, Region command are replaced by <Body> commands and optionally one <PointList> block. All these elements must be within the single <MaterialPoints> element in the input file:

<MaterialPoints>
  <PointList>
    (see help on PointList block)
  </PointList>
 
  <Body mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' thick='(thick)' angle='(angle)' 
                   temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
    <MatlPtsPerElement>(totalNumber)</MatlPtsPerElement> (see note 1)
    (interspersed initial velocity commands)
    (interspersed initial angular velocity commands)
    (any number of shape commands)
    (interspersed <Deform> and <Undeform> commands)
    (interspersed rotation commands)
  </Body>

  ....
</MaterialPoints>

where

(matid) is the material ID for a previously defined material (or can reference by material name).
(velx), (vely), and (velz) are the components of the initial velocity for all particles in the region (velz is only used for 3D simulations). The units are velocity units. In scripted input files, the velocities can be numerical constants or can be user defined functions of particle position. The values of the functions are applied to all particles in the region. In XML input files, the velocites must be numerical constants, but you can set position dependent velocities by using initial velocity commands within the <Body> element.
(thick) is the thickness of each material point in length units. The thickness is only used for planar 2D calculations. In scripted files for axisymmetric calculations, the thickness parameter is still required, but it is only used for parameter alignment (its value is ignored).
(totalNumber) is to optionally set the number of material points in each element of the background grid for this region to differ from the default setting.¹ (it must be square or cube of points per side in 2D or 3D, respectively). This option is for XML files only. Use the "res" option below to pick points per element in scripted file.

Besides the above required parameters, you can provide optional parameters to set initial conditions for all particles in the region. In scripted files, the optional parameters appear in pairs. The first item in the pair (i.e., (property)) is the name of the property to set and the second item (i.e., (value)) is the initial value for that property. In XML files, the optional properties are set using optional attributes:

angle,(angle) to set the initial rotation angle for the material axes about the z axis. The units are degrees. This parameter is sufficient for 2D analyses with constant material angle. See help on setting material angles for methods to set variable angles or to set more than one rotation angle in 3D calculations.
temp,(temp) to set the initial particle temperature. The units are degrees.
conc,(conc) to set the initial particle concentration potential. The dimensionless concentration potential must be from 0 to 1. Only used when doing diffusion calculations.
(wtconc)to set concentration by weight fraction concentration instead of by concentration potential. The resulting potential will be (wtconc) divided by the material's saturation concentration. This option is only available in XML input files. The units are dimensionless and must be from 0 to the material's saturation concentration. Only used when doing diffusion calculations.
pp,(pp) to set the initial particle pore pressure in pressure units. Only used when doing poroelasticity calculations.
res,(axisNumber) is to optionally set the number of material points along each axis in each element of the background grid for this region to differ from the default setting.¹ The total number of points per element is square (for 2D) or cube (for 3D) of (axisNumber).

Besides these particle properties, other material point properties some Particle-Based Boundary Conditions set initial values for particles (e.g., particle damage state).

The optional PointList Block can be used to define individual material points, each with individual initial conditions. The option is only available to XML input files.

Shape Commands

Between the Region command and the subsequent EndRegion command (or within each <Body> element), there can be any number of shape commands to define material point positions and the shapes. The details on these shape command are given elsewhere:

By nesting shapes, you can create many more types of shapes.

Hole Commands

The Hole command is used to designate regions of the background grid that should not have material points. In scripted files, the Hole command is:

Hole
  (any number of shape commands)
EndHole

In XML files, the <Hole> block is:

<Hole>
  (any number of shape commands)    
</Hole>

Between the Hole command and the subsequent EndHole command (or within the <Hole> block), there can be any number of shape commands to define hole locations. The details on these shape command are given elsewhere:

By nesting shapes, you can create many more types of shapes.

An object with holes (or voids) is created by a sequence of Region and Hole commands. Each Region command fills every location within its shapes with a material point unless that location was previously designated as a hole. Each Hole command designates every location within its shapes as being a hole, but, if any location already has a material point, that point is left intact. In other words, the order of these commands is crucial. By selecting the correct order, you have greatly flexibility in creating objects with solid regions and void (or hole) regions.

Membrane Particles

Membrane material points can only be added using XML commands by added <Membrane> elements with the <MaterialPoints> element. The options are currently very limited. In 2D. membrane particles can only be added along a straight lines using an <MemLine> element. In 3D, the only option is particle within a flat plane using <MemPlane> element. In 2D, the details are:

<MaterialPoints>
  <Membrane mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' angle='(angle)' 
                   temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
    <MemLine y1='(y1)' y2='(y2)' x1='(x1)' x2='(x2)' tolerance='(tol)' thickness='(mthick)' length='(mlen)'/>
    (interspersed initial velocity commands)
    (interspersed initial angular velocity commands)
  </Membrane>
  ....
</MaterialPoints>

where attributes on the <Membrane> are the same as those defined for the <Body> element and the material must be a membrane material type. The first five attributes on the <MemLine> element the same as those for a Line command. The last two set membrane particle properties:

(mthick) to set thickness of membranes in the 2D plane of the analysis (the (thick) property on <Membrane> elements sets thickness in z direction).
(mlen) to set length of each particle along the line (the line is divided into an integral number of material points). Membrane lines should have at least two membrane particles per background cell and can benefit from having more.

In 3D, the details are:

<MaterialPoints>
  <Membrane mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' thick='(thick)' angle='(angle)' 
                   temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
    <MemPlane xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)' zmin='(zmin)' zmax='(zmax)'
                   length='(length)' memaxis='(memaxis)'/>
    (interspersed initial velocity commands)
    (interspersed initial angular velocity commands)
  </Membrane>
  ....
</MaterialPoints>

where attributes on the <Membrane> are the same as those defined for the <Body> element and the material must be a membrane material type. The first six attributes on the <MemPlane> element the same as those for a Box command. The last two set membrane particle properties:

(length) to set length for sides of membrane particles within the plane. Membrane planes should have at least two particles in each background cell directon and can benefit from having more.
(memaxis) is normal direction to the plane of particles. This command is currently limited to planes normal to x, y, or z axis. The thickness of membrane particles normal to the place is found from limits of that plane (e.g., when (memaxis)=z, the particle thicknesses are set to (zmax)-(zmin).

Simulations can combine standard, solid material point types with membrane materials points. Because the code does not check if membrane particle overlap other material points, the user is responsible for defining non-overlapping regions in simulations that use membranes or that combine membranes with solid material points.

Membranes can be added in scripting input files but putting the XML command inside an XMLData Command block where first parameter adds the data to the MaterialPoint element. For example:

XMLData "MaterialPoints"
   <Membrane mat="&MemMat;" thick="&thick;" vx="0" vy="0">
     <MemLine y1="&yloc;" y2="&yloc;" x1="0" x2="&xmax;" thickness="&mthick;" length="&mlen;"/>
   </Membrane>
EndXMLData

Notice defining terms in Entity commands is a good way to couple scripting commands to XML data blocks.

Notes

If you set the number of material points per element in a region that differs from the default setting, the code will no longer check to make sure particles are not overlapping. The user is therefore responsible for defining non-overlapping regions. Note also that this setting can use any valid number per element and is not limited to the values allowed when choosing the default setting.

@@ Line 1: / Line 1: @@
 In MPM, the most common way to discretize an object is to add material points to the [[MPM Grid Generation|background grid]] using <tt>Region</tt> commands  and to designate regions of the grid has having no material points using <tt>Hole</tt> commands. Enclosed in these commands are various shape commands to define the object. An alternative and powerful option for discretizing an object is to [[BMPRegion Command|create material points automatically from an image of the object]].
+When modeling with [[Material Models#Membrane Materials|membrane materials]] (which are only in [[OSParticulas]]), membrane material points are added with <tt>&lt;Membrane&gt;</tt> <tt>XML</tt> elements.
 __TOC__
 == Region Commands ==
-Once the [[MPM Grid Generation|background grid is created]], material points are added to the grid using a series of <tt>Region</tt> commands (or <tt><Body></tt> commands in <tt>XML</tt> files). In scripted files, the <tt>Region</tt> command defines material type, initial velocity, thickness (in 2D), and optionally an [[Setting Material Orientation|initial angle]] (for some [[Material Models|anisotropic materials]]), temperature, and concentration. The command is
+Once the [[MPM Grid Generation|background grid is created]], material points are added to the grid using a series of <tt>Region</tt> commands. In scripted files, the <tt>Region</tt> command defines material type, initial velocity, thickness (in 2D), and optionally an [[Setting Material Orientation|initial angle]] (for some [[Material Models|anisotropic materials]]), temperature, and concentration. The command is
   Region (matid),(velx),(vely),(velz) or (thick),<(property),(value)>...
-    (any number of shape commands)
+   (an [[Setting Material Point Initial Velocity#Setting Initial Angular Velocity|initial angular velocity command]])
+    (any number of [[#Shape Commands|shape commands]])
+   (one optional [[Transform Command]])
+   (interspersed [[Setting Material Orientation|rotation commands]])
   EndRegion
-In <tt>XML</tt> files, regions are defined using <tt><Body></tt> elements and optional one <tt>PointList</tt> element. All these element must be withinthe single <tt>MaterialPoints</tt> element in the input file:
+In <tt>XML</tt> files, <tt>Region</tt> command are replaced by <tt><Body></tt> commands and optionally one <tt><PointList></tt> block. All these elements must be within the single <tt><MaterialPoints></tt> element in the input file:
   <MaterialPoints>
     <PointList>
-      (see help on creating individual material points)
+      (see help on PointList block)
     </PointList>
-    <Body mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' thick='(thick)'
+    <Body mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' thick='(thick)' angle='(angle)'
-                          angle='(angle)' temp='(temp)' conc='(conc)' wtconc='(wtconc)'>
+                    temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
-      (any number of shape commands)
+     <MatlPtsPerElement>(totalNumber)</MatlPtsPerElement> (see [[#Notes|note 1]])
+     (interspersed [[Setting Material Point Initial Velocity|initial velocity commands]])
+     (interspersed [[Setting Material Point Initial Velocity#Setting Initial Angular Velocity|initial angular velocity commands]])
+      (any number of [[#Shape Commands|shape commands]])
+     (interspersed [[Transform Command|<Deform> and <Undeform> commands]])
+     (interspersed [[Setting Material Orientation|rotation commands]])
     </Body>
@@ Line 26: / Line 37: @@
 where
-* <tt>(matid)</tt> is the material ID for a previously defined [[Material Command Block|material]].
+* <tt>(matid)</tt> is the material ID for a previously defined [[Material Command Block|material]] (or can reference by [[Material Command Block#Referencing Materials in XML Files|material name]]).
-* <tt>(velx)</tt>, <tt>(vely)</tt>, and <tt>(velz)</tt> are the components of the initial velocity for for all particles in the region (<tt>velx</tt> is only used for 3D simulations). The units or mm/sec
+* <tt>(velx)</tt>, <tt>(vely)</tt>, and <tt>(velz)</tt> are the components of the initial velocity for all particles in the region (<tt>velz</tt> is only used for 3D simulations). The units are [[ConsistentUnits Command#Legacy and Consistent Units|velocity units]]. In scripted input files, the velocities can be numerical constants or can be [[User Defined Functions|user defined functions]] of particle position. The values of the functions are applied to all particles in the region. In <tt>XML</tt> input files, the velocites must be numerical constants, but you can set position dependent velocities by using [[Setting Material Point Initial Velocity|initial velocity commands]] within the <tt><Body></tt> element.
-* <tt>(thick)</tt> is the thickness of each material point in mm. The thickness is only used for planar 2D calculations. In scripted files, the thickness parameter should still be provided for parameter alignment, although its value is ignored.
+* <tt>(thick)</tt> is the thickness of each material point in [[ConsistentUnits Command#Legacy and Consistent Units|length units]]. The thickness is only used for planar 2D calculations. In scripted files for axisymmetric calculations, the thickness parameter is still required, but it is only used for parameter alignment (its value is ignored).
+* <tt>(totalNumber)</tt> is to optionally set the number of material points in each element of the background grid for this region to differ from the default setting.[[#Notes|<sup>1</sup>]] (it must be square or cube of points per side in 2D or 3D, respectively). This option is for <tt>XML</tt> files only. Use the "res" option below to pick points per element in scripted file.
-After the above required parameters, you can provide one to three optional parameters to set initial conditions for all particles in the region. In scripted files, the optional parameters appear in pairs. The first item in the pair, or <tt>(property)</tt>, is the name of initial property to set and the second item, or <tt>(value)</tt>, is the initial value for the property. In <tt>XML</tt> files, the optional parameters are three optional attributes:
+Besides the above required parameters, you can provide optional parameters to set initial conditions for all particles in the region. In scripted files, the optional parameters appear in pairs. The first item in the pair (''i.e.'', <tt>(property)</tt>) is the name of the property to set and the second item (''i.e.'', <tt>(value)</tt>) is the initial value for that property. In <tt>XML</tt> files, the optional properties are set using optional attributes:
-* <tt>angle,(angle)</tt> to set the initial rotation angle for the material axes about the z axis. The units are degrees. This parameter is sufficient for 2D analysis with constant material angle. See help on [[Setting Material Orientation|setting material angles]] for methods to set variable angles or to set more than on rotation angle in 3D calculations.
+* <tt>angle,(angle)</tt> to set the initial rotation angle for the material axes about the z axis. The units are degrees. This parameter is sufficient for 2D analyses with constant material angle. See help on [[Setting Material Orientation|setting material angles]] for methods to set variable angles or to set more than one rotation angle in 3D calculations.
 * <tt>temp,(temp)</tt> to set the initial particle temperature. The units are degrees.
-* <tt>conc,(conc)</tt> to set the initial particle [[Diffusion Calculations#Diffusion Material Properties|concentration potential]]. The dimensionless concentration potential must be from 0 to 1. Only used when doing [[Diffusion Calculations|diffusion]] calculations.
+* <tt>conc,(conc)</tt> to set the initial particle [[Diffusion Calculations#Diffusion Material Properties|concentration potential]]. The dimensionless concentration potential must be from 0 to 1. Only used when doing [[Diffusion Calculations|diffusion calculations]].
-* <tt>(wtconc)</tt>to set concentration use weight fraction concentration (0 to 1) instead of [[Diffusion Calculations#Diffusion Material Properties|concentration potential]]. The resulting potential will <tt>(wtcon)</tt> divided by the material's [[Common Material Properties#Basic Properties|saturation concentration]]. This option is only available in <tt>XML</tt> input files. The units are dimensionless and must be from 0 to the material's [[Common Material Properties#Basic Properties|saturation concentration]]. Only used when doing [[Diffusion Calculations|diffusion]] calculations.
+* <tt>(wtconc)</tt>to set concentration by weight fraction concentration instead of by [[Diffusion Calculations#Diffusion Material Properties|concentration potential]]. The resulting potential will be <tt>(wtconc)</tt> divided by the material's [[Common Material Properties#Basic Properties|saturation concentration]]. This option is only available in <tt>XML</tt> input files. The units are dimensionless and must be from 0 to the material's [[Common Material Properties#Basic Properties|saturation concentration]]. Only used when doing [[Diffusion Calculations|diffusion calculations]].
+* <tt>pp,(pp)</tt> to set the initial particle pore pressure in [[ConsistentUnits Command#Legacy and Consistent Units|pressure units]]. Only used when doing [[Poroelasticity Calculations|poroelasticity calculations]].
+* <tt>res,(axisNumber)</tt> is to optionally set the number of material points along each axis in each element of the background grid for this region to differ from the default setting.[[#Notes|<sup>1</sup>]] The total number of points per element is square (for 2D) or cube (for 3D) of <tt>(axisNumber)</tt>.
+Besides these particle properties, other material point properties some [[Particle-Based Boundary Conditions]] set initial values for particles (''e.g.'', particle damage state).
+The optional [[PointList Block]] can be used to define individual material points, each with individual initial conditions. The option is only available to <tt>XML</tt> input files.
+=== Shape Commands ===
-Between the <tt>Region</tt> command and the subsequent <tt>EndRegion</tt> command (or within the <tt><Body></tt> element), there can be any number of shape commands to define material point positions. The details on these shape command are given elsewhere:
+Between the <tt>Region</tt> command and the subsequent <tt>EndRegion</tt> command (or within each <tt><Body></tt> element), there can be any number of shape commands to define material point positions and the shapes. The details on these shape command are given elsewhere:
 * [[2D MPM Shape Commands]]
 * [[3D MPM Shape Commands]]
-* [[PointList Block]]
+By [[Nested Shapes|nesting shapes]], you can create many more types of shapes.
 == Hole Commands ==
-The <tt>Hole</tt> command is used to designate regions of the grid that should not have any material points. In scripted files, the <tt>Hole</tt> command is:
+The <tt>Hole</tt> command is used to designate regions of the [[MPM Grid Generation|background grid]] that should not have material points. In scripted files, the <tt>Hole</tt> command is:
   Hole
@@ Line 62: / Line 83: @@
 * [[3D MPM Shape Commands]]
-An object with holes is create by a sequence of [[#Region Commands|<tt>Region</tt>]] and <tt>Hole</tt> commands. Each [[#Region Commands|<tt>Region</tt> command]] fills every location within its shapes with a material point unless that location was previous designated as a hole. Each <tt>Hole</tt> command designates every location within its shapes as not having a material point, but, if the a location already has a material point, that point is left intact. In other words, the order of these commands is crucial. By selecting the correctly order, you have greatly flexibility in creating objects with solid regions and void (or hole) regions.
+By [[Nested Shapes|nesting shapes]], you can create many more types of shapes.
+An object with holes (or voids) is created by a sequence of [[#Region Commands|<tt>Region</tt>]] and <tt>Hole</tt> commands. Each [[#Region Commands|<tt>Region</tt> command]] fills every location within its shapes with a material point unless that location was previously designated as a hole. Each <tt>Hole</tt> command designates every location within its shapes as being a hole, but, if any location already has a material point, that point is left intact. In other words, the order of these commands is crucial. By selecting the correct order, you have greatly flexibility in creating objects with solid regions and void (or hole) regions.
+== Membrane Particles ==
+[[Material Models#Membrane Material|Membrane material points]] can only be added using <tt>XML</tt> commands by added <tt>&lt;Membrane&gt;</tt> elements with the <tt>&lt;MaterialPoints&gt;</tt> element. The options are currently very limited. In 2D. membrane particles can only be added along a straight lines using an <tt>&lt;MemLine&gt;</tt> element. In 3D, the only option is particle within a flat plane using <tt>&lt;MemPlane&gt;</tt> element. In 2D, the details are:
+ <MaterialPoints>
+   <Membrane mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' angle='(angle)'
+                    temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
+     <MemLine y1='(y1)' y2='(y2)' x1='(x1)' x2='(x2)' tolerance='(tol)' thickness='(mthick)' length='(mlen)'/>
+     (interspersed [[Setting Material Point Initial Velocity|initial velocity commands]])
+     (interspersed [[Setting Material Point Initial Velocity#Setting Initial Angular Velocity|initial angular velocity commands]])
+   </Membrane>
+   ....
+ </MaterialPoints>
+where attributes on the <tt>&lt;Membrane&gt;</tt> are the same as those defined for the [[#Region Commands|<tt>&lt;Body&gt;</tt> element]] and the material must be a [[Material Models#Membrane Materials|membrane material type]]. The first five attributes on the <tt>&lt;MemLine&gt;</tt> element the same as those for a [[2D MPM Shape Commands#Line Command|Line command]]. The last two set membrane particle properties:
+* <tt>(mthick)</tt> to set thickness of membranes in the 2D plane of the analysis (the <tt>(thick)</tt> property on <tt>&lt;Membrane&gt;</tt> elements sets thickness in <tt>z</tt> direction).
+* <tt>(mlen)</tt> to set length of each particle along the line (the line is divided into an integral number of material points). Membrane lines should have at least two membrane particles per background cell and can benefit from having more.
+In 3D, the details are:
+ <MaterialPoints>
+   <Membrane mat='(matid)' vx='(velx)' vy='(vely)' vz='(velz)' thick='(thick)' angle='(angle)'
+                    temp='(temp)' conc='(conc)' wtconc='(wtconc)' pp='(pp)'>
+     <MemPlane xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)' zmin='(zmin)' zmax='(zmax)'
+                    length='(length)' memaxis='(memaxis)'/>
+     (interspersed [[Setting Material Point Initial Velocity|initial velocity commands]])
+     (interspersed [[Setting Material Point Initial Velocity#Setting Initial Angular Velocity|initial angular velocity commands]])
+   </Membrane>
+   ....
+ </MaterialPoints>
+where attributes on the <tt>&lt;Membrane&gt;</tt> are the same as those defined for the [[#Region Commands|<tt>&lt;Body&gt;</tt> element]] and the material must be a [[Material Models#Membrane Materials|membrane material type]].
+The first six attributes on the <tt>&lt;MemPlane&gt;</tt> element the same as those for a [[3D MPM Shape Commands#Box Command|Box command]]. The last two set membrane particle properties:
+* <tt>(length)</tt> to set length for sides of membrane particles within the plane. Membrane planes should have at least two particles in each background cell directon and can benefit from having more.
+* <tt>(memaxis)</tt> is normal direction to the plane of particles. This command is currently limited to planes normal to <tt>x</tt>, <tt>y</tt>, or <tt>z</tt> axis. The thickness of membrane particles normal to the place is found from limits of that plane (''e.g.'', when <tt>(memaxis)=z</tt>, the particle thicknesses are set to <tt>(zmax)-(zmin)</tt>.
+Simulations can combine standard, solid material point types with membrane materials points. Because the code does not check if membrane particle overlap other material points, the user is responsible for defining non-overlapping regions in simulations that use membranes or that combine membranes with solid material points.
+Membranes can be added in scripting input files but putting the <tt>XML</tt> command inside an [[XMLData Command]] block where first parameter adds the data to the <tt>MaterialPoint</tt> element. For example:
+ XMLData "MaterialPoints"
+    <Membrane mat="&MemMat;" thick="&thick;" vx="0" vy="0">
+      <MemLine y1="&yloc;" y2="&yloc;" x1="0" x2="&xmax;" thickness="&mthick;" length="&mlen;"/>
+    </Membrane>
+ EndXMLData
+Notice defining terms in [[Entity Command|Entity commands]] is a good way to couple scripting commands to <tt>XML</tt> data blocks.
+== Notes ==
+<ol>
+<li>If you set the number of material points per element in a region that differs from the [[MPM Methods and Simulation Timing#Input Commands|default setting]], the code will no longer check to make sure particles are not overlapping. The user is therefore responsible for defining non-overlapping regions. Note also that this setting can use any valid number per element and is not limited to the values allowed when choosing the [[MPM Methods and Simulation Timing#Input Commands|default setting]].</li>
+</ol>