lmcv-tools 0.0.32
Command line tool that provides useful functionalities to LMCV Members
Requires Python: >=3.10

# LMCV Tools

## 1 - Introduction

LMCV Tools is a **command line tool**  that provides a series of useful functionalities for the day-to-day simulations of the "Laboratório de Mecânica Computacional e Visualização" of the "Universidade Federal do Ceará" (UFC).

### 1.1 - Install

```text
$ pip install lmcv_tools
```

### 1.2 - Update to Last Version

```text
$ pip install --upgrade lmcv_tools
```

### 1.3 - Build and Install from Source

```text
$ pip install build
$ python -m build
$ pip install dist/[name of wheel file].whl
```

### 1.4 - How to Use

Once installed, the basic form of the LMCV Tools commands is:

```text
$ lmcv_tools [command] [flags] [args]
```

To check the installed version, use the command below:

```text
$ lmcv_tools version
```

To get help, it's possible use the following command:

```text
$ lmcv_tools help
```

To start ***Interactive Mode***, do not type any command and then you can type multiple commands in sequence:

```text
$ lmcv_tools
[Welcome Message]
>> [command]
output
>> [other command]
other output
```

For more complex commands, check out the detailed descriptions in the next section.

---

## 2 - Complex Commands

Considering that the routine activities for which LMCV Tools was developed are quite varied, specific commands were developed for each one of them. These commands are:
- translate (in implementation)
- extract (in implementation)
- generate (in implementation)
- reorder
- change (in implementation)

### 2.1 - Translate

The command **translate**, in short, aims to convert different types of files used in LMCV.

Its usage is quite simple:

```text
$ lmcv_tools translate [path/to/file] to [extension]
```

### 2.1.1 - Translate .inp to .dat

Abaqus is a suite for Finite Element Analysis (FEA) developed by "Dassault Systèmes", while FAST is a console based FEA tool developed by "Laboratório de Mecânica Computacional e Visualização" of "Universidade Federal do Ceará" (UFC). Both of these softwares can simulate complex problems, but FAST has a clear disadvantage: differently of Abaqus, it hasn't a native GUI to generate its meshes. With that in mind, this command specifically seeks to translate meshes generated in Abaqus and exported in .inp format into meshes in .dat format to be used in FAST simulations.

Example:
```text
$ lmcv_tools translate Job-1.inp to .dat
```

### 2.1.2 - Translate .dat to .svg

Articles for scientific publications in the LMCV study field generally require images of the used meshes. Generating bitmat images in PNG format is a valid possibility, but for very discretized meshes this approach results in loss of details. Thinking about it, this command translates .dat files of **plate and shell** meshes to the SVG (Scalable Vector Graphics) image format, which does not lose quality with zoom (perfect for meshes with many elements).

Example:
```text
$ lmcv_tools translate Plate.dat to .svg
```

In addition, this command has some flags:

| Flags              | Description                                                      |
| ---                | ---                                                              |
| -p or --projection | Type of projection: parallel or perspective (default: parallel). |
| -x                 | X-coordinate of the projection center (perspective projection).  |
| -y                 | Y-coordinate of the projection center (perspective projection).  |
| -z                 | Z-coordinate of the projection center (perspective projection).  |
| --Rx               | A rotaion in x-axis.                                             |
| --Ry               | A rotaion in y-axis.                                             |
| --Rz               | A rotaion in z-axis.                                             |

Examples:
```text
$ lmcv_tools translate Plate.dat to .svg --projection=parallel

$ lmcv_tools translate Plate.dat to .svg -p=perspective -x=0 -y=0 -=30

$ lmcv_tools translate Plate.dat to .svg --Rx=45.0 --Ry=30.0

$ lmcv_tools translate Plate.dat to .svg -p=perspective -x=0 -y=20 -=40.0 --Rx=45.0 --Ry=30.0 --Rx=34
```

The use of these flags must consider the following points:
- The projection plane will always be the **x-y plane**.
- The -x, -y and -z flags are only necessary if the projection type is “perspective”.
- The coordinates provided in the -x, -y and -z flags are relative to the **mesh centroid**.
- The flags --Rx, --Ry and --Rz can be written in any order and **can even be repeated**.
- The rotations described by --Rx, --Ry, and --Rz will be executed in the order they were written.

### 2.2 - Extract

The command **extract**, in short, aims to extract data from .pos (or .dat) files generated by FAST and save this data in CSV format.

Files with extension ".pos" are the standard output from FAST simulations. They can store data about nodal displacements, element stresses, gauss points stresses and other informations, all distributed over a series of steps. In some contexts, it is necessary to obtain specific data from these files, but the manual search can take a lot of time and still fail. Alternatively, this command allows to extract entire set of related atributes by a simple expression.

An extraction expression can be broken down into terms:
- Keywords
- Attributes
- Condition

**Keywords** are a set of words that define the commmand syntax. In this command, the keywords are "from", "where" and "to" (the last two are optional). Examples of valid syntaxes are:

```text
$ lmcv_tools extract [atributes] from [path/to/.pos]
$ lmcv_tools extract [atributes] from [path/to/.pos] to [path/to/.csv]
$ lmcv_tools extract [atributes] from [path/to/.pos] where [condition]
$ lmcv_tools extract [atributes] from [path/to/.pos] where [condition] to [path/to/.csv]
```

**Attributes** are names that represent a piece of data from a .pos file. The supported attributes are:

| Attribute                      | Type  | Sub-Type | Related Attributes                |
| ---                            | ---   | ---      | ---                               |
| step.id                        | int   | -        | -                                 |
| step.factor                    | float | -        | step.id                           |
| node.id                        | int   | -        | -                                 |
| node.coord                     | list  | float    | node.id                           |
| step.node.displacement         | list  | float    | step.id, node.id                  |
| step.gauss.scalar              | list  | str      | step.id                           |
| step.nodal.scalar              | list  | str      | step.id                           |
| element.id                     | int   | -        | -                                 |
| element.info                   | list  | int      | element.id                        |
| step.element.gauss.scalar.data | list  | float    | step.id, element.id               |
| step.element.nodal.scalar.data | list  | float    | step.id, element.id               |
| buckling.id                    | int   | -        | -                                 |
| buckling.factor                | float | -        | buckling.id                       |
| buckling.node.displacement     | list  | float    | buckling.id, node.id              |
| vibration.id                   | int   | -        | -                                 |
| vibration.factor               | float | -        | vibration.id                      |
| vibration.node.displacement    | list  | float    | vibration.id, node.id             |
| material.id                    | int   | -        | -                                 |
| material.isotropic.E           | float | -        | material.id                       |
| material.isotropic.poisson     | float | -        | material.id, material.isotropic.E |
| section.id                     | int   | -        | -                                 |
| section.bar.circle.radius      | float | -        | section.id                        |

Attributes that share any related attributed can be related in order which they were typed. Example:

```text
$ lmcv_tools extract step.id step.factor step.node.displacement[0] from Example.pos
```

**Condition** is a series of attribute constraints. They can be written intuitively using attributes, operators and test values after "from" keyword. The supported operators are:

| Operator | Meaning                              |
| ---      | ---                                  |
| and      | Logical and.                         |
| or       | Logical or.                          |
| =        | Relational equal to.                 |
| >        | Relational gerater than.             |
| <        | Relational less than.                |
| >=       | Relational gerater than or equal to. |
| <=       | Relational less than or equal to.    |
| !=       | Relational different from.           |
| in       | Relational membership.               |

Remembering that the symbols ">" and "<" must be encapsulated by quotes. Otherwise, they will be interpreted by the shell as ***redirection operators***.

Examples:

```text
$ lmcv_tools extract step.factor from Example.pos where step.id ">" 2
```

```text
$ lmcv_tools extract step.factor from Example.pos where step.id != 3 and step.factor ">" 3
```

### 2.3 - Generate

The command **generate**, in short, aims to create special artifacts.

Artifact is a broad term for anything that can be useful for LMCV simulations. They can be file templates, dynamically generated file parts or anything else that needs a shortcut to create.

Possible Syntaxes:

```text
$ lmcv_tools generate [artifact name]
$ lmcv_tools generate [artifact name] [args] [path/to/artifact]
```

Implemented artifacts are listed below:
- virtual_laminas
- cuboid

#### 2.3.1 - Virtual Laminas
Virtual Laminas (virtual_laminas) are a model that approximates the behavior of a Functionally Graded Material. The idea is to represent these materials as a stack of isotropic homogeneous laminas. The more laminas used, the more accurate the simulation results. However, tools like Abaqus or FAST do not have a fast and automated way to generate these laminas, so this artifact was developed as a solution.

This syntax below will start a graphical interface to facilitate the process of passing arguments:

```text
$ lmcv_tools generate virtual_laminas
```

Other syntax possible is based in a long and exaustive list of required arguments:

```text
$ lmcv_tools generate virtual_laminas [params] [path/to/virtual_laminas]
```

| Parameters            | Type  | Description                                          |
| ---                   |---    | ---                                                  |
| Laminas Count         | int   | Total number of laminas.                             |
| Laminas Thickness     | float | Thinkcness of laminas.                               |
| Power Law Exponent    | float | Exponent of Power Law.                               |
| Micromechanical Model | str   | Model to calculate effective properties.             |
| Element Type          | str   | Supported: Solid, Shell.                             |
| E1                    | float | Elastic Modulus of Material 1.                       |
| E2                    | float | Elastic Modulus of Material 2.                       |
| nu1                   | float | Poisson's Coefficient of Material 1.                 |
| nu2                   | float | Poisson's Coefficient of Material 2.                 |
| pho1                  | float | Density of Material 1.                               |
| pho2                  | float | Density of Material 2.                               |
| Smart Laminas         | bool  | If True, a new smart generation method will be used. |

**Supported Micromechanical Models:**
- voigt
- mori_tanaka
- hashin_shtrikman_lower_bound
- hashin_shtrikman_upper_bound

#### 2.3.2 - Rectangle
Rectangles are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of rectangles in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate rectangle [params] [path/to/rectangle]
```

| Parameters   | Type  | Description                   |
| ---          |---    | ---                           |
| Element Type | str   | Supported: Q8.                |
| Width        | float | Cuboid Width (x).             |
| Height       | float | Cuboid Height (y).            |
| Nx           | int   | Number of Elements in Width.  |
| Ny           | int   | Number of Elements in Height. |

#### 2.3.3 - Cuboid
Cuboids are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of cuboids in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate cuboid [params] [path/to/cuboid]
```

| Parameters   | Type  | Description                   |
| ---          |---    | ---                           |
| Element Type | str   | Supported: BRICK20.           |
| Width        | float | Cuboid Width (x).             |
| Height       | float | Cuboid Height (y).            |
| Deep         | float | Cuboid Deep (z).              |
| Nx           | int   | Number of Elements in Width.  |
| Ny           | int   | Number of Elements in Height. |
| Nz           | int   | Number of Elements in Deep.   |

#### 2.3.4 - NURBS Rectangles
NURBS Rectangles are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of NURBS meshes of Rectangles in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate nurbs_rectangle [params] [path/to/nurbs_rectangle]
```

| Parameters   | Type  | Description                   |
| ---          |---    | ---                           |
| Dx           | int   | Degree in Width.              |
| Dy           | int   | Degree in Height.             |
| Width        | float | Cuboid Width (x).             |
| Height       | float | Cuboid Height (y).            |
| Nx           | int   | Number of Elements in Width.  |
| Ny           | int   | Number of Elements in Height. |

#### 2.3.5 - NURBS Cuboid
NURBS Cuboids are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of NURBS meshes of Cuboids in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate nurbs_cuboid [params] [path/to/nurbs_cuboid]
```

| Parameters   | Type  | Description                   |
| ---          |---    | ---                           |
| Dx           | int   | Degree in Width.              |
| Dy           | int   | Degree in Height.             |
| Dz           | int   | Degree in Deep.               |
| Width        | float | Cuboid Width (x).             |
| Height       | float | Cuboid Height (y).            |
| Deep         | float | Cuboid Deep (z).              |
| Nx           | int   | Number of Elements in Width.  |
| Ny           | int   | Number of Elements in Height. |
| Nz           | int   | Number of Elements in Deep.   |

#### 2.3.6 - Cylindrical Panel
Cylindrical panels are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of cylindrical panels in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate cyl_panel [params] [path/to/cyl_panel]
```

| Parameters   | Type  | Description                     |
| ---          |---    | ---                             |
| Element Type | str   | Supported: Q8, Q4.              |
| Height       | float | Cuboid Height (y).              |
| Nx           | int   | Number of Elements in Width.    |
| Ny           | int   | Number of Elements in Height.   |
| Radius       | float | Panel Radius.                   |
| Start Angle  | float | Angle to start panel (Degrees). |
| Stop Angle   | float | Angle to stop panel (Degrees).  |

#### 2.3.7 - Slit Annular Plate
Slit annular plates are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of slit annular plates in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate slit_annular_plate [params] [path/to/slit_annular_plate]
```

| Parameters   | Type  | Description                             |
| ---          |---    | ---                                     |
| Element Type | str   | Supported: Q8.                          |
| Inner Radius | float | Plate Inner Radius.                     |
| Outer Radius | float | Plate Outer Radius.                     |
| Nr           | int   | Number of Elements along Radius.        |
| Nc           | int   | Number of Elements along Circunference. |

#### 2.3.8 - NURBS Slit Annular Plate
NURBS slit annular plates are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of slit annular plates in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate nurbs_slit_annular_plate [params] [path/to/nurbs_slit_annular_plate]
```

| Parameters   | Type  | Description                                     |
| ---          |---    | ---                                             |
| Inner Radius | float | Plate Inner Radius.                             |
| Outer Radius | float | Plate Outer Radius.                             |
| Dr           | int   | Element Degree along Radius.                    |
| Dc           | int   | Element Degree along Circunference quarter.     |
| Nr           | int   | Number of Elements along Radius.                |
| Nc           | int   | Number of Elements along Circunference quarter. |

#### 2.3.9 - NURBS Hemisfere
NURBS hemisfere are geometric shapes frequently used in simulation tests. Therefore, this artifact was created to allow the generation of finite element meshes of hemisferes in .dat format.

Proper Syntax:

```text
$ lmcv_tools generate nurbs_hemisfere [params] [path/to/nurbs_hemisfere]
```

| Parameters   | Type  | Description                                          |
| ---          |---    | ---                                                  |
| Radius       | float | Hemisfere Radius.                                    |
| Pole Angle   | float | Hemisfere Pole Angle.                                |
| Dl           | int   | Element Degree along Longitudinal Circunference.     |
| Dt           | int   | Element Degree along Transversal Circunference.      |
| Nl           | int   | Number of Elements along Longitudinal Circunference. |
| Nt           | int   | Number of Elements along Transversal Circunference.  |

### 2.4 - Reorder

The command **reorder**, in short, aims to add a node solver order in .dat files to reduce the stiffiness matrix bandwidth and, consequently, the time spent to execute the simulation.

Considering that computational simulations based on the finite element method involve the solution of a system of linear equations, it is possible to reduce the execution time of these simulations by also reducing the bandwidth of the stiffness matrix that represents the linear system. A valid approach for this is the reordering of the nodes that make up the simulation mesh. Thus, this command allows generating a reordering of nodes (a new node solver order) from different methods.

Possible Syntax:
```text
$ lmcv_tools reorder [method] [path/to/.dat]
```

Example:
```text
$ lmcv_tools reorder rcm simulation.dat
```

**Possible Flags:**
| Flag         | Function                                               |
| ---          | ---                                                    |
| -i or --info | Show info about bandwidth reduction and execution time |

**Supported Reordering Methods**:
| Keyword     | Method                                                              |
| ---         | ---                                                                 |
| rcm         | [[1]](#3---references) Reverse Cuthill-McKee                        |
| sloan       | [[2]](#3---references) Sloan                                        |
| boost_rcm   | Boost C++ Library Implementation of Reverse Cuthill-McKee Algorithm |
| boost_sloan | Boost C++ Library Implementation of Sloan Algorithm                 |

### 2.5 - Change

The command **change**, in short, aims to change certain values from .dat (or .pos) files generated by FAST.

Files with extension ".dat" are the standard input from FAST simulations. They can store data about nodal coordinates, material properties, section details and other informations. In some contexts, it is necessary to change specific data from these files, but the manual process can take a lot of time and still fail. Alternatively, this command allows to precisely change specific atributes by a simple expression.

In a similar way to the command extract, a change expression can be broken down into terms:
- Keywords
- Attributes
- Condition

**Keywords** are a set of words that define the command syntax. In this command, the keywords are "to", "in" and "where" (the last is optional). Examples of valid syntaxes are:

```text
$ lmcv_tools change [atribute] to [value] in [path/to/.dat]
$ lmcv_tools change [atribute] to [value] in [path/to/.pos] where [condition]
```

**Attributes** are names that represent a piece of data from a .dat (or .pos) file. They are the same as those used in the extract command. Example:

```text
$ lmcv_tools change material.isotropic.poisson to 0.3 in Example.dat
```

**Condition** is a series of attribute constraints. They can be written intuitively using attributes, operators and test values after "from" keyword, just like the command extract. However, in this specific case, only attributes related to the attribute that will be changed can be used in condition expressions. Example:

```text
$ lmcv_tools change material.isotropic.poisson to 0.3 in Example. where material.id = 2
```

## 3 - References

- [1] CUTHILL, E.; MCKEE, J.. Reducing the bandwidth of sparse symmetric matrices. Proceedings of The 1969 24th National Conference, Washington, p. 157-172, 26 ago. 1969. ACM Press. http://dx.doi.org/10.1145/800195.805928.
- [2] SLOAN, S. W.. An algorithm for profile and wavefront reduction of sparse matrices. International Journal for Numerical Methods in Engineering, Newcastle, v. 23, n. 2, p. 239-251, fev. 1986. Wiley. http://dx.doi.org/10.1002/nme.1620230208.