User Manual — turbo-turtle 1.2.9 documentation

Skip to main content
`Ctrl`+`K`

# User Manual

Turbo Turtle is a wrapper around common modeling operations in Abaqus [1] and Cubit [2]. As much as possible, the work for each subcommand is perfomed in Python 3 [3] to minimize solution approach duplication. Turbo Turtle makes a best effort to maintain common behaviors and features across each third-party software’s modeling concepts.

## Quick Start

1. View the CLI usage

       $ turbo-turtle -h
       $ turbo-turtle docs -h
       $ turbo-turtle geometry -h
       $ turbo-turtle cylinder -h
       $ turbo-turtle sphere -h
       $ turbo-turtle partition -h
       $ turbo-turtle mesh -h
       $ turbo-turtle image -h
       $ turbo-turtle merge -h
       $ turbo-turtle export -h

## Installation

This project builds and deploys as a Conda package [4, 5] and PyPI/pip package.

### Conda

Turbo-Turtle can be installed in a Conda environment with the Conda package manager. See the Conda installation and Conda environment management documentation for more details about using Conda.

    $ conda install --channel conda-forge turbo_turtle

### pip

Turbo-Turtle may also be installed from PyPI with pip under the distribution name `turbo-turtle`: https://pypi.org/project/turbo-turtle/.

    $ pip install turbo-turtle

The PyPI package has an optional dependency for the Gmsh features that may be specified during installation as

    $ pip install turbo-turtle[gmsh]

## Examples: Abaqus

Turbo Turtle was originally written using Abaqus as the backend modeling and meshing software. Most of the interface options and descriptions use Abaqus modeling concepts and language. See the Command Line Utilities documentation for additional subcommands and options.

### Three-dimensional sphere

1. Create the geometry

       turbo-turtle sphere --inner-radius 1 --outer-radius 2 --output-file sphere.cae --model-name sphere --part-name sphere

2. Partition the geometry

       turbo-turtle partition --input-file sphere.cae --output-file sphere.cae --model-name sphere --part-name sphere

3. Mesh the geometry

       turbo-turtle mesh --input-file sphere.cae --output-file sphere.cae --model-name sphere --part-name sphere --element-type C3D8 --global-seed 0.15

4. Create an assembly image

       turbo-turtle image --input-file sphere.cae --output-file sphere.png --model-name sphere --part-name sphere

5. Export an orphan mesh

       turbo-turtle export --input-file sphere.cae --model-name sphere --part-name sphere

### Two-dimensional, axisymmetric sphere

1. Create the geometry

       turbo-turtle sphere --inner-radius 1 --outer-radius 2 --output-file axisymmetric.cae --model-name axisymmetric --part-name axisymmetric --revolution-angle 0

2. Partition the geometry

       turbo-turtle partition --input-file axisymmetric.cae --output-file axisymmetric.cae --model-name axisymmetric --part-name axisymmetric

3. Mesh the geometry

       turbo-turtle mesh --input-file axisymmetric.cae --output-file axisymmetric.cae --model-name axisymmetric --part-name axisymmetric --element-type CAX4 --global-seed 0.15

4. Create an assembly image

       turbo-turtle image --input-file axisymmetric.cae --output-file axisymmetric.png --model-name axisymmetric --part-name axisymmetric

5. Export an orphan mesh

       turbo-turtle export --input-file axisymmetric.cae --model-name axisymmetric --part-name axisymmetric

## Examples: Cubit

These examples are (nearly) identical to the Abaqus examples above, but appended with the `--backend cubit` option. Because the commands are (nearly) identical, they will be included as a single command block. See the Command Line Utilities documentation for caveats in behavior for the Cubit implementation and translation of Abaqus language to Cubit language. The list of commands will be expanded as they are implemented.

Note

- The `--model-name` option has no corresponding Cubit concept and is ignored in all Cubit implementations.

- The mesh subcommand `--element-type` option maps to the Cubit meshing scheme concept. It is only used if a non-default scheme is passed: trimesh or tetmesh. Because the Abaqus and Cubit implementations share a command line parser, and the Abaqus implementation requires this option, it is always required in the Cubit implementation as well.

- The image subcommand must launch a Cubit window and the Cubit commands only work in APREPRO journal files, so an `output_file`.jou file is created.

### Three-dimensional sphere

    turbo-turtle sphere --inner-radius 1 --outer-radius 2 --output-file sphere.cub --part-name sphere --backend cubit
    turbo-turtle partition --input-file sphere.cub --output-file sphere.cub --part-name sphere --backend cubit
    turbo-turtle mesh --input-file sphere.cub --output-file sphere.cub --part-name sphere --element-type dummy --global-seed 0.15 --backend cubit
    turbo-turtle image --input-file sphere.cub --output-file sphere.png --backend cubit
    turbo-turtle export --input-file sphere.cub --part-name sphere --backend cubit

### Two-dimensional, axisymmetric sphere

    turbo-turtle sphere --inner-radius 1 --outer-radius 2 --output-file axisymmetric.cub --part-name axisymmetric --revolution-angle 0 --backend cubit
    turbo-turtle partition --input-file axisymmetric.cub --output-file axisymmetric.cub --part-name axisymmetric
    turbo-turtle mesh --input-file axisymmetric.cub --output-file axisymmetric.cub --part-name axisymmetric --element-type dummy --global-seed 0.15
    turbo-turtle image --input-file axisymmetric.cub --output-file axisymmetric.png --backend cubit
    turbo-turtle export --input-file axisymmetric.cub --part-name axisymmetric

## SCons extensions

Turbo Turtle includes extensions to the SCons [6, 7] build system in the External API scons_extensions module. These may be used when importing Turbo Turtle as a Python package in an SCons configuration file. For example:

SConstruct

      1#! /usr/bin/env python
      2import os
      3import inspect
      4import pathlib
      5
      6import waves
      7import turbo_turtle
      8
      9
     10# Accept command line options with fall back default values
     11AddOption(
     12    "--build-dir",
     13    dest="variant_dir_base",
     14    default="build",
     15    nargs=1,
     16    type=str,
     17    action="store",
     18    metavar="DIR",
     19    help="SCons build (variant) root directory. Relative or absolute path. (default: '%default')",
     20)
     21AddOption(
     22    "--turbo-turtle-command",
     23    dest="turbo_turtle_command",
     24    default="turbo-turtle",
     25    nargs=1,
     26    type="string",
     27    action="store",
     28    metavar="COMMAND",
     29    help="Override for the Turbo-Turtle command (default: '%default')",
     30)
     31AddOption(
     32    "--abaqus-command",
     33    dest="abaqus_command",
     34    default="abaqus",
     35    nargs=1,
     36    type="string",
     37    action="store",
     38    metavar="COMMAND",
     39    help="Override for the Abaqus command (default: '%default')",
     40)
     41AddOption(
     42    "--cubit-command",
     43    dest="cubit_command",
     44    default="cubit",
     45    nargs=1,
     46    type="string",
     47    action="store",
     48    metavar="COMMAND",
     49    help="Override for the Cubit command (default: '%default')",
     50)
     51
     52env = waves.scons_extensions.WAVESEnvironment(
     53    ENV=os.environ.copy(),
     54    variant_dir_base=pathlib.Path(GetOption("variant_dir_base")),
     55    turbo_turtle_command=GetOption("turbo_turtle_command"),
     56)
     57env.PrintBuildFailures()
     58import pdb; pdb.set_trace()
     59
     60# Find required programs for conditional target ignoring and absolute path for use in target actions
     61abaqus_commands = [f'"{env.CheckProgram(GetOption("abaqus_command"))}"']
     62cubit_commands = [f'"{env.CheckProgram(GetOption("cubit_command"))}"']
     63
     64env.Append(BUILDERS={
     65    "TurboTurtleSphere": turbo_turtle.scons_extensions.sphere(
     66        program=env["turbo_turtle_command"],
     67        options="--model-name ${model_name} --part-name ${part_name} --backend ${backend}",
     68        abaqus_command=abaqus_commands,
     69        cubit_command=cubit_commands,
     70    ),
     71    "TurboTurtlePartition": turbo_turtle.scons_extensions.partition(
     72        program=env["turbo_turtle_command"],
     73        options="--model-name ${model_name} --part-name ${part_name} --backend ${backend}",
     74        abaqus_command=abaqus_commands,
     75        cubit_command=cubit_commands,
     76    ),
     77    "TurboTurtleMesh": turbo_turtle.scons_extensions.mesh(
     78        program=env["turbo_turtle_command"],
     79        options="--model-name ${model_name} --part-name ${part_name} --backend ${backend} --global-seed ${global_seed}",
     80        abaqus_command=abaqus_commands,
     81        cubit_command=cubit_commands,
     82    ),
     83    "TurboTurtleImage": turbo_turtle.scons_extensions.image(
     84        program=env["turbo_turtle_command"],
     85        options="--model-name ${model_name} --part-name ${part_name} --backend ${backend}",
     86        abaqus_command=abaqus_commands,
     87        cubit_command=cubit_commands,
     88    ),
     89    "TurboTurtleExport": turbo_turtle.scons_extensions.export(
     90        program=env["turbo_turtle_command"],
     91        options="--model-name ${model_name} --part-name ${part_name} --backend ${backend}",
     92        abaqus_command=abaqus_commands,
     93        cubit_command=cubit_commands,
     94    )
     95})
     96
     97for backend, extension in [("abaqus", "cae"), ("cubit", "cub")]:
     98    build_dir = env["variant_dir_base"] / backend
     99    SConscript("SConscript", variant_dir=build_dir, exports=["env", "backend", "extension"], duplicate=False)
    100
    101env.Default()
    102
    103waves.scons_extensions.project_help()

SConscript

     1#! /usr/bin/env python
     2Import("env", "backend", "extension")
     3
     4workflow = []
     5
     6workflow.extend(env.TurboTurtleSphere(
     7    target=[f"sphere_geometry.{extension}"],
     8    source=["SConscript"],
     9    inner_radius=1.,
    10    outer_radius=2.,
    11    model_name="sphere",
    12    part_name="sphere",
    13    backend=backend
    14))
    15
    16workflow.extend(env.TurboTurtlePartition(
    17    target=[f"sphere_partition.{extension}"],
    18    source=[f"sphere_geometry.{extension}"],
    19    model_name="sphere",
    20    part_name="sphere",
    21    backend=backend
    22))
    23
    24workflow.extend(env.TurboTurtleMesh(
    25    target=[f"sphere_mesh.{extension}"],
    26    source=[f"sphere_partition.{extension}"],
    27    element_type="C3D8",
    28    global_seed=0.15,
    29    model_name="sphere",
    30    part_name="sphere",
    31    backend=backend
    32))
    33
    34workflow.extend(env.TurboTurtleImage(
    35    target=[f"sphere_mesh.png"],
    36    source=[f"sphere_mesh.{extension}"],
    37    model_name="sphere",
    38    part_name="sphere",
    39    backend=backend
    40))
    41
    42workflow.extend(env.TurboTurtleExport(
    43    target=[f"sphere.inp"],
    44    source=[f"sphere_mesh.{extension}"],
    45    model_name="sphere",
    46    part_name="sphere",
    47    backend=backend
    48))
    49
    50env.Alias(backend, workflow)