# pycbg.preprocessing.Simulation

class `pycbg.preprocessing.``Simulation`(title='Sim_title', directory='')

  Create a simulation.

  Parameters

    - title (str, optional) – Simulation title. Default is ‘Sim_title’.

    - directory (str, optional) – Path to the simulation’s directory. Mesh, particles and entity sets files will be saved in this directory. The result folder is also set to be created by CB-Geo in this directory. Default is title.

  `mesh`

    Simulation’s mesh. Created using the create_mesh method.

    Type

      `Mesh` object

  `particles`

    Simulation’s particles. Created using the create_particles method.

    Type

      `Particles` object

  `entity_sets`

    Simulation’s entity sets. Created using the init_entity_sets method.

    Type

      `EntitySets` object

  `materials`

    Simulation’s materials. Created upon creating the Simulation object.

    Type

      `Materials` object

  `init_stresses`

    Initial stresses for each particle. Noting npart the number of particles, its shape is `(npart, 3)`.

    Type

      numpy array

  `input_filename`

    Path to the input file.

    Type

      str

  `title`

    Simulation title.

    Type

      str

  `directory`

    Path to the simulation’s directory.

    Type

      str

  Notes

  Mesh, Particles, EntitySets and `Materials` objects are created from the Simulation object.

  Examples

  Simulating under gravity a column made of two materials :

      >>> sim = Simulation()
      >>> sim.create_mesh(dimensions=(1.,1.,10.), ncells=(1,1,10))
      >>> sim.create_particles(npart_perdim_percell=1)
      >>> sim.init_entity_sets()
      >>> lower_particles = sim.entity_sets.create_set(lambda x,y,z: z<10, typ="particle")
      >>> upper_particles = sim.entity_sets.create_set(lambda x,y,z: z>=10, typ="particle")
      >>> sim.materials.create_MohrCoulomb3D(pset_id=lower_particles)
      >>> sim.materials.create_Newtonian3D(pset_id=upper_particles)
      >>> walls = []
      >>> walls.append([sim.entity_sets.create_set(lambda x,y,z: x==lim, typ="node") for lim in [0, sim.mesh.l0]])
      >>> walls.append([sim.entity_sets.create_set(lambda x,y,z: y==lim, typ="node") for lim in [0, sim.mesh.l1]])
      >>> walls.append([sim.entity_sets.create_set(lambda x,y,z: z==lim, typ="node") for lim in [0, sim.mesh.l2]])
      >>> for direction, sets in enumerate(walls): _ = [sim.add_velocity_condition(direction, 0., es) for es in sets]
      >>> sim.set_gravity([0,0,-9.81])
      >>> sim.set_analysis_parameters(dt=1e-3, nsteps=1.5e8, output_step_interval=7.5e6)
      >>> sim.write_input_file()

  `__init__`(title='Sim_title', directory='')

    Initialize self. See help(type(self)) for accurate signature.

  Methods

  `__init__` | Initialize self.
  `add_friction_condition` | Add a friction condition on a node set.
  `add_math_function` | Add a math function to the simulation.
  `add_nodal_force` | Add a force on all the node in a node set.
  `add_velocity_condition` | Add a velocity condition on a node or particle set.
  `create_mesh` | Create the simulation’s mesh.
  `create_particles` | Create the simultation’s particles.
  `init_entity_sets` | Create the simulation’s `EntitySets` object.
  `set_analysis_parameters` | Set the analysis parameters.
  `set_gravity` | Set the value of gravity.
  `set_initial_particles_stresses` | Set the initial stresses for each particle.
  `write_input_file` | Write the input file.

  `add_friction_condition`(dir, sgn_n, frict_value, node_set)

    Add a friction condition on a node set.

    Parameters

      - dir ({0, 1, 2}) – Axis of the normal vector to the plane where friction is acting.

      - sgn_n ({-1, 1}) – Sign of the normal vector to the plane where friction is acting.

      - vel_value (float) – Imposed friction coefficient’s value.

      - entity_set (int) – Id of the entity set on which the velocity is imposed.

      - typ ({"node", "particle"}, optional) – Type of set on which the velocity is imposed. Default is “particle”.

  `add_math_function`(function_wrt_time)

    Add a math function to the simulation.

    Parameters

      function_wrt_time (function) – Function that take the time t as input and returns the value of the math function.

    Notes

    Should be called after analysis parameters are set (since the time values are computed from the time step and number of steps).

    Returns

      Id of the math function just appended.

    Return type

      int

  `add_nodal_force`(dir, force, node_set, math_function_id=None)

    Add a force on all the node in a node set.

    Parameters

      - dir ({0, 1, 2}) – Axis on which the force is imposed.

      - force (float) – Imposed force’s value (\(N\)).

      - node_set (int) – Id of the node set on which the force is imposed.

      - math_function_id (int, optional) – Id of the math function to use. Default value is None (the load is then static).

  `add_velocity_condition`(dir, vel_value, entity_set, typ='node')

    Add a velocity condition on a node or particle set.

    Parameters

      - dir ({0, 1, 2}) – Axis on which the velocity is imposed.

      - vel_value (float) – Imposed velocity’s value (\(m.s^{-1}\)).

      - entity_set (int) – Id of the entity set on which the velocity is imposed.

      - typ ({"node", "particle"}, optional) – Type of set on which the velocity is imposed. Default is “particle”.

  `create_mesh`(*args, **kwargs)

    Create the simulation’s mesh.

    Parameters

      - dimensions (tuple of floats) – Dimensions of the mesh. Its length should be 3, with dimensions[n] the dimension of the mesh on the axis n.

      - ncells (tuple of ints) – Number of cells in each direction. Its length should be 3, with ncells[n] the number of cells on the axis n.

      - check_duplicates (bool, optional) – See CB-Geo documentation for informations on this parameter. Default is True.

      - cell_type ({'ED3H8', 'ED3H20', 'ED3H64'}, optional) – Type of cell. Only 3D Hexahedrons are supported. The number of nodes can be 8, 20 or 64. Default is ‘ED3H8’.

  `create_particles`(*args, **kwargs)

    Create the simultation’s particles.

    Parameters

      - npart_perdim_percell (int, optional) – Number of particles for each dimensions in one cell. All cells will contain `npart_perdim_percell**3` equally spaced particles. Note that particles are equally spaced within a cell, not between cells. Default is 1 .

      - check_duplicates (bool, optional) – See CB-Geo documentation for informations on this parameter. Default is True.

  `init_entity_sets`()

    Create the simulation’s `EntitySets` object.

    Has to be called after mesh and particles creation.

  `set_analysis_parameters`(type='MPMExplicit3D', mpm_scheme='usl', damping=0.05, locate_particles=False, dt=1e-05, velocity_update=False, nsteps=2000, output_step_interval=100)

    Set the analysis parameters. Has to be called before write_input_file.

    Parameters

      - type ({'MPMExplicit2D', 'MPMExplicit3D'}, optional) – Analysis type. Default is ‘MPMExplicit3D’.

      - mpm_scheme ({'usf', 'usl', 'musl'}, optional) – MPM scheme for the stress update. The scheme can be “Update Stress First” (‘usf’), “Update Stress Last” (‘usl’) or “Modified Update Stress Last” (‘musl’).

      - damping (float, optional) – Cundall’s damping. Should verify : `0 <= damping < 1`. Default is 0.05 .

      - locate_particles (bool, optional) – Stops the simulation when particles go outside the mesh if True. Default is False.

      - dt (float, optional) – Time step (\(s\)). Default is 1e-5 \(s\).

      - velocity_update (bool, optional) – How to compute velocity. If True nodal velocity is directly interpolated from particles, if False nodal velocity is computed from the acceleration interpolated from particles. Default is False.

      - nsteps (int, optional) – Number of steps to be performed. Default is 2000.

      - output_step_interval (int, optional) – Number of steps between two data points. Default is 100.

  `set_gravity`(gravity)

    Set the value of gravity. If this method isn’t called, gravity is [0,0,0].

    Parameters

      gravity (list of floats) – Gravity’s value on each axis (\(m/s^2\)).

  `set_initial_particles_stresses`(init_stresses)

    Set the initial stresses for each particle.

    Parameters

      init_stresses (numpy array) – Initial stresses for each particle. Noting npart the number of particles, it should have the shape `(npart, 3)`.

  `write_input_file`()

    Write the input file.