<filename>SRC/tutorials/unusualmesh.py
# -*- python -*-

# This software was produced by NIST, an agency of the U.S. government,
# and by statute is not subject to copyright in the United States.
# Recipients of this software assume all responsibilities associated
# with its operation, modification and maintenance. However, to
# facilitate maintenance we ask that before distributing modified
# versions of this software, you first contact the authors at
# <EMAIL>. 


from ooflib.tutorials import tutorial
TutoringItem = tutorial.TutoringItem
TutorialClass = tutorial.TutorialClass

TutorialClass(
    subject = "Nonrectangular Domain",
    ordering=5,
    lessons = [
    
    TutoringItem(
    subject="Introduction",
    comments=

    """Meshes (Skeletons) that are generated by OOF3D are always
    RECTANGULAR.  However, it doesn't mean that
    you're limited only to a rectangular domain.
    
    OOF3D allows you to simulate arbitrarily shaped problem domains by
    selectively assigning materials to a Microstructure.

    In this tutorial, we will cover this topic in detail.
    """),

    TutoringItem(
    subject="Microstructure",
    comments=
    
    """Open a graphics window, if none has been opened yet, with
    the BOLD(Graphics/New) command in the BOLD(Windows) menu.

    Download and unpack the file BOLD(el_shape.tar.gz) from
    http://www.ctcms.nist.gov/oof/oof3d/examples, or locate
    BOLD(el_shape) within the share/oof3d/examples directory in your
    OOF3D installation.
    
    Open the BOLD(Microstructure) page and click BOLD(New from Image
    File) to create a new microstructure.  In the file selection
    dialog box, navigate to BOLD(el_shape).  Click BOLD(OK) to
    load the Image and create the Microstructure.

    """,
    signal = ("new who", "Microstructure")
    ),
    
    TutoringItem(
    subject="Categorizing Voxels",
    comments=

    """The microstructure features BOLD(green) and BOLD(ivory) regions.
    We're interested only in the BOLD(green) region -- our problem
    domain will be an BOLD(L)-shaped bracket, so to speak.

    To categorize voxels automatically,
    open the BOLD(Image) page and click the BOLD(Group) button.
    
    Go back to the BOLD(Microstructure) page and you will see that
    BOLD(2) voxel groups have been created for the microstructure.
    """ ),

    TutoringItem(
    subject="Voxel Group",
    comments=

    """Now, we'll change names of voxel groups for our convenience.

    Go to the BOLD(Microstructure) page and select the second voxel
    group, named BOLD(#00ff00), which represents BOLD(green) voxels.
    Click the BOLD(Rename) button.

    Replace the old name with "green".

    Don't bother with the other voxel group, since we're not going to
    use it.
    """,
    
    signal="renamed pixel group"),

    TutoringItem(
    subject="Material",
    comments=
    """Open the BOLD(Materials) page.
    Create a new material by clicking on the BOLD(New) button in the
    BOLD(Material) pane.

    Click the check box for non-generic name, and type BOLD(green-material)
    in the text entry field.
    Click BOLD(OK).
    """,
    signal="new_material"
    ),

    TutoringItem(
    subject="Property",
    comments=

    """Start creating a property for BOLD(green-material) by selecting
    BOLD(Isotropic) from BOLD(Mechanical->Elasticity)
    in the property hierarchy.

    Click BOLD(Copy) and check the box to give it a user-defined name.

    Check the box and type in BOLD(green_elasticity). Click
    BOLD(OK).""",

    signal = "new property"
    ),

    TutoringItem(
    subject="Parametrizing Property",
    comments=
    
    """Select BOLD(green_elasticity) from the Property hierarchy and
    either double click it or click the BOLD(Parametrize...) button to
    input actual values.

    The elasticity parameters can be entered in a variety of formats.
    The default format is BOLD(Cij).  Change it to BOLD(E and nu) with
    the pull down menu at the top of the Parametrize dialog box.

    Set the modulus of elasticity (BOLD(young)) to 1.0 and Poisson's ratio
    (BOLD(poisson)) to 0.3.

    Click BOLD(OK) to finish up.
    """,
    signal = "redraw"
    ),

    TutoringItem(
    subject="Adding Property to Material",
    comments=

    """Select BOLD(green_elasticity) from the Property tree.

    Click BOLD(Add Property to Material) from the bottom of
    the BOLD(Property) pane to add the Property to the Material.

    The addition should immediately appear in the BOLD(Material) pane,
    in the list of Properties below the Material selector.
    """,
    signal= "prop_added_to_material"
    ),

    TutoringItem(
    subject="Assigning Material to Voxels",
    
    comments=
    
    """Select the material BOLD(green-material) and click on the
    button labelled BOLD(Assign Material to Voxels...) in the
    BOLD(Material) pane.

    The pop-up window lets you choose the Microstructure to which the
    Material will be assigned (currently we only have one,
    "el_shape"), and the voxels within the Microstructure.  Choose
    the voxel group BOLD(green) in the BOLD(voxels) pull-down menu.

    Click BOLD(OK) to finish.

    We will NOT do anything for the BOLD(ivory) voxels.
    """,
    signal = "materials changed in microstructure"
    ),

    TutoringItem(
    subject="Skeleton",
    comments=

    """Go to the BOLD(Skeleton) page.
    Click BOLD(New...) to create an initial skeleton.

    Use these  values for the initial skeleton: BOLD(x_elements) = 10,
    BOLD(y_elements) = 10, BOLD(z_elements) = 10, and 
    BOLD(skeleton_geometry)=TetraSkeleton. Click BOLD(OK) to create
    the Skeleton.
    """,
        
    signal = ("new who", "Skeleton")
    ),

    TutoringItem(
    subject="Boundary Modification",
    comments=

    """
    Some of the predefined Skeleton boundaries include edges of
    non-green elements.  Since we're only interested in the
    BOLD(green) portion of the Skeleton, we're going to modify the
    existing boundaries.
    
    We'll modify four faces boundaries, BOLD(Ymax), BOLD(Xmax), 
    BOLD(Zmin) and BOLD(Zmax) so that only the segments from the
    BOLD(green) elements will be part of them.  Advance to the next
    slide for real action.
    """
    ),

    TutoringItem(
    subject="Boundary Modification 1",
    comments=

    """Go to the BOLD(Skeleton Boundaries) page. Select the BOLD(Zmax)
    boundary from the BOLD(Boundaries) pane. Now, if you go to the
    graphics window, you will see that the selected face boundary is
    displayed by orange arrow points sticking through the element
    faces.  (You may need to BOLD(Tumble) the graphics window to see
    them clearly).  What we're going to do is to remove the faces of
    the BOLD(ivory) elements from this boundary.  Unselect the
    boundary by control-clicking on its name in the BOLD(Boundaries)
    pane.  (On Macs in non-X11 mode, use command-click.)

    First, select the ivory elements.  Open the BOLD(Skeleton
    Selection) toolbox in the graphics window.  Select BOLD(Element)
    from the selection modes. Choose BOLD(ByDominantPixel) for the
    selection method. Now select all the elements that belong to
    BOLD(ivory) elements boundaries by clicking on that area.

    Next, select the outside faces of the ivory elements.  Put the
    BOLD(Skeleton Selection) page in the main OOF3D window into
    BOLD(Faces) mode.  Set BOLD(Method) to BOLD(From Selected
    Elements), with BOLD(coverage) set to BOLD(Exterior) and
    BOLD(operator) set to BOLD(Select).  Click BOLD(OK).
    """,
        
    signal = "face selection modifier applied"
    ),

    TutoringItem(
    subject="Boundary Modification 2",
    comments=

    """Now we'll remove all the ivory faces from the BOLD(Xmax),
    BOLD(Ymax), BOLD(Zmax) and BOLD(Zmin) boundaries.  Go back to the
    BOLD(Skeleton Boundaries) page, select one of the boundaries, and
    click BOLD(Modify).  Set the BOLD(modifier) to BOLD(Remove faces)
    with BOLD(group) set to BOLD(<selection>).  Click BOLD(OK).

    Repeat the process for the other three boundaries.

    In the BOLD(Skeleton Selection) page or toolbox you can now clear
    the element and face selections.

    Now, we're ready to create a Mesh from this Skeleton.
    """,
    signal = "new boundary configuration"
    ),
    
    TutoringItem(
    subject="Finite Element Mesh",
    comments=
    """Open the BOLD(FE Mesh) page.

    Click the BOLD(New) button to get a dialog box for creating a new
    Mesh.

    Leave the default values in place, and click BOLD(OK).

    As you recall, we didn't assign any material to the BOLD(ivory)
    elements.  These elements will be dummies, which makes the Mesh
    (even if it's rectangular) an effective L-shaped domain.  If you
    hide or delete the BOLD(Skeleton) and BOLD(Image) layers in the
    BOLD(Graphics) window, you'll see that Mesh elements are drawn
    only where a Material has been assigned.

    Now, let us solve a problem using this Mesh.
    """,
    signal = ("new who", "Mesh")
    ),

    TutoringItem(
    subject=" Field & Equations",
    comments=

    """Proceed to the BOLD(Fields & Equations) page.
    
    Check both boxes for the BOLD(Displacement) field.

    We're solving a BOLD(Force_Balance) equation,
    so check the corresponding box.
    """,
    signal =  "equation activated"
    ),

    TutoringItem(
    subject="Boundary Conditions",
    comments="""Go to the BOLD(Boundary Conditions) page.

    The boundary conditions (all BOLD(Dirichlet)) we're going to apply are:

    BOLD(1.) u_x = 0 on the BOLD(Xmin) side
    
    BOLD(2.) u_y = 0 on the BOLD(Xmin) side

    BOLD(3.) u_z = 0 on the BOLD(Xmin) side

    BOLD(4.) u_y = -2 on the BOLD(Xmax) side"""
    ),

    TutoringItem(
    subject="Boundary Condition 1",
    comments=
    """Click the BOLD(New...) button from the BOLD(Condition) pane to bring
    up a boundary condition builder.  The pull-down menu at the top of
    the dialog box allows you to choose the type of boundary
    condition.  Set it to BOLD(Dirichlet), which
    gives associated Fields fixed values at the boundaries.
    
    Since only one Field is defined and only one Equation is active,
    the BOLD(field) and BOLD(equation) menus have only one choice
    each.  Leave them set to BOLD(Displacement) and
    BOLD(Force_Balance).
 
    The first B.C. deals with displacement in the BOLD(x)-direction,
    so select BOLD(x) for both BOLD(field_component) and
    BOLD(eqn_component).

    The BOLD(profile) is the functional form of the Field along the
    boundary.  Set BOLD(profile) to BOLD(Constant Profile) with BOLD(value) = 0.

    Choose the BOLD(boundary) to which this condition should
    be applied (BOLD(Xmin)) and click BOLD(OK).
    """,
    signal = "boundary conditions changed"
    ),

    TutoringItem(
    subject="Boundary Condition 2-4",
    comments=
    """Create the rest of Boundary Conditions as you did for the first one.
    You can always go back to previous slides to check some numbers and
    stuff by clicking on the BOLD(Back) button. BUT, make sure
    to create all the BCs before you move on to the next slide.

    (If you get back to this page and discover that the BOLD(Next)
    button is disabled, just edit one of the boundary conditions by
    double clicking it or using the BOLD(Edit) button.  You don't
    actually have to change the boundary condition, you just have to
    trick the tutorial machinery into thinking you've changed
    something.)
    """,
    
    signal = "boundary conditions changed"
    ),

    TutoringItem(
    subject="Solution",
    comments=
    
    """Open the BOLD(Solver) page.  Set the Basic/Static/Iterative
    solver for the default subproblem.  Set the Displacement
    initializer to (0, 0, 0), apply the initializer, and click
    BOLD(Solve).  The deformed Mesh will be displayed in the graphics
    window.
    """),
     ])
