PyMAPDL command line interface#
For your convenience, PyMAPDL package includes a command line interface which allows you to launch, stop, list, and execute commands on MAPDL instances.
Launch MAPDL instances#
To start MAPDL, just type on your activated virtual environment:
(.venv) PS C:\Users\user\pymapdl> pymapdl start
Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052
(.venv) user@machine:~$ pymapdl start
Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052
If you want to specify an argument, for instance the port, then you need to call launch_mapdl start:
(.venv) PS C:\Users\user\pymapdl> pymapdl start --port 50054
Success: Launched an MAPDL instance (PID=18238) at 127.0.0.1:50054
(.venv) user@machine:~$ pymapdl start --port 50054
Success: Launched an MAPDL instance (PID=18238) at 127.0.0.1:50054
This pymapdl start command uses the
ansys.mapdl.core.launcher.launch_mapdl_process() function internally
to start MAPDL without creating a client connection. The command returns the
connection information (IP, port, and PID) that you can use to connect later.
Some of the arguments that ansys.mapdl.core.launcher.launch_mapdl() allows
are also available in the CLI. For instance, you could specify the working directory:
(.venv) PS C:\Users\user\pymapdl> pymapdl start --run_location C:\Users\user\temp\
Success: Launched an MAPDL instance (PID=32612) at 127.0.0.1:50052
(.venv) user@machine:~$ pymapdl start --run_location /home/user/tmp
Success: Launched an MAPDL instance (PID=32612) at 127.0.0.1:50052
For more information about the underlying function, see
ansys.mapdl.core.launcher.launch_mapdl_process().
Stop MAPDL instances#
You can use the pymapdl stop command to stop MAPDL instances like this:
(.venv) PS C:\Users\user\pymapdl> pymapdl stop
Success: Ansys instances running on port 50052 have been stopped.
(.venv) user@machine:~$ pymapdl stop
Success: Ansys instances running on port 50052 have been stopped.
By default, the instance running on the port 50052 is stopped.
You can specify the instance running on a different port using –port argument:
(.venv) PS C:\Users\user\pymapdl> pymapdl stop --port 50053
Success: Ansys instances running on port 50053 have been stopped.
(.venv) user@machine:~$ pymapdl stop --port 50053
Success: Ansys instances running on port 50053 have been stopped.
Or an instance with a given process id (PID):
(.venv) PS C:\Users\user\pymapdl> pymapdl stop --pid 40952
Success: The process with PID 40952 and its children have been stopped.
(.venv) user@machine:~$ pymapdl stop --pid 40952
Success: The process with PID 40952 and its children has been stopped.
Alternatively, you can stop all the running instances by using:
(.venv) PS C:\Users\user\pymapdl> pymapdl stop --all
Success: Ansys instances have been stopped.
(.venv) user@machine:~$ pymapdl stop --all
Success: Ansys instances have been stopped.
List MAPDL instances and processes#
You can also list MAPDL instances and processes. If you want to list MAPDL process, just use the following command:
(.venv) PS C:\Users\user\pymapdl> pymapdl list
Name Is Instance Status gRPC port PID
------------ ------------- -------- ----------- -----
ANSYS.exe False running 50052 35360
ANSYS.exe False running 50052 37116
ANSYS241.exe True running 50052 41644
(.venv) user@machine:~$ pymapdl list
Name Is Instance Status gRPC port PID
------------ ------------- -------- ----------- -----
ANSYS.exe False running 50052 35360
ANSYS.exe False running 50052 37116
ANSYS241.exe True running 50052 41644
If you want, to just list the instances (avoiding listing children MAPDL processes), just type:
(.venv) PS C:\Users\user\pymapdl> pymapdl list -i
Name Status gRPC port PID
------------ -------- ----------- -----
ANSYS241.exe running 50052 41644
(.venv) user@machine:~$ pymapdl list -i
Name Status gRPC port PID
------------ -------- ----------- -----
ANSYS241.exe running 50052 41644
You can also print other fields like the working directory (using –cwd) or the command line (using -c). Additionally, you can also print all the available information by using the argument –long or -l:
(.venv) PS C:\Users\user\pymapdl> pymapdl list -l
Name Is Instance Status gRPC port PID Command line Working directory
------------ ------------- -------- ----------- ----- -------------------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------
ANSYS.exe False running 50052 35360 C:\Program Files\ANSYS Inc\v241\ANSYS\bin\winx64\ANSYS.EXE -j file -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp
ANSYS.exe False running 50052 37116 C:\Program Files\ANSYS Inc\v241\ANSYS\bin\winx64\ANSYS.EXE -j file -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp
ANSYS241.exe True running 50052 41644 C:\Program Files\ANSYS Inc\v241\ansys\bin\winx64\ansys241.exe -j file -np 2 -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp
(.venv) user@machine:~$ pymapdl list -l
Name Is Instance Status gRPC port PID Command line Working directory
------------ ------------- -------- ----------- ----- ------------------------------------------------------------------------- --------------------------------
ANSYS False running 50052 35360 /ansys_inc/v241/ansys/bin/linx64/ansys -j file -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp
ANSYS False running 50052 37116 /ansys_inc/v241/ansys/bin/linx64/ansys -j file -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp
ANSYS241 True running 50052 41644 /ansys_inc/v241/ansys/bin/linx64/ansys241 -j file -np 2 -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp
The converter module has its own command line interface to convert MAPDL files to PyMAPDL. For more information, see Convert APDL code.
Execute MAPDL commands#
Use pymapdl exec to send APDL commands to a running MAPDL instance and
print the output to stdout. The command always connects to an existing
instance, it never starts a new one. Use pymapdl start first if needed.
There are three mutually exclusive ways to supply commands. The recommended
approach is to use the -c / --command option, which can be repeated.
Each -c value is one APDL command; all commands are sent as a single block:
(.venv) PS C:\Users\user\pymapdl> pymapdl exec -c /prep7 -c "BLOCK,0,1,0,1,0,1" -c SAVE
(.venv) user@machine:~$ pymapdl exec -c /prep7 -c "BLOCK,0,1,0,1,0,1" -c SAVE
You can also read commands from an APDL script file using --file / -f:
(.venv) PS C:\Users\user\pymapdl> pymapdl exec --file my_script.inp
(.venv) user@machine:~$ pymapdl exec --file my_script.inp
To pipe commands from another program, pass - as a positional argument to
read from stdin:
(.venv) PS C:\Users\user\pymapdl> Get-Content my_script.inp | pymapdl exec -
(.venv) user@machine:~$ cat my_script.inp | pymapdl exec -
By default, pymapdl exec connects without clearing the MAPDL database, so
successive calls share the same model state. Use the --clear-on-connect
flag to clear the database before sending commands:
(.venv) PS C:\Users\user\pymapdl> pymapdl exec --clear-on-connect -c /prep7
(.venv) user@machine:~$ pymapdl exec --clear-on-connect -c /prep7
A common workflow is to start MAPDL once, send one or more command blocks, and then stop the instance:
(.venv) PS C:\Users\user\pymapdl> pymapdl start
Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052
(.venv) PS C:\Users\user\pymapdl> pymapdl exec -c /prep7 -c "BLOCK,0,1,0,1,0,1"
(.venv) PS C:\Users\user\pymapdl> pymapdl exec -c SAVE
(.venv) PS C:\Users\user\pymapdl> pymapdl stop
Success: Ansys instances running on port 50052 have been stopped.
(.venv) user@machine:~$ pymapdl start
Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052
(.venv) user@machine:~$ pymapdl exec -c /prep7 -c "BLOCK,0,1,0,1,0,1"
(.venv) user@machine:~$ pymapdl exec -c SAVE
(.venv) user@machine:~$ pymapdl stop
Success: Ansys instances running on port 50052 have been stopped.
Note
pymapdl exec writes command output to stdout and errors to stderr,
making it suitable for use in shell scripts and pipelines. The process
exits with code 0 on success and 1 on failure.
To convert an existing APDL script to Python instead of executing it, see Convert APDL code.
Convert APDL code#
After you have activated and installed the package as described
in Installation, you can use the converter from your terminal.
Here is how you use the pymapdl convert command:
(.venv) PS C:\Users\user\pymapdl> pymapdl convert mapdl.dat -o python.py
The ``mapdl.dat`` file is successfully converted to the ``python.py`` file.
(.venv) user@machine:~$ pymapdl convert mapdl.dat -o python.py
File mapdl.dat successfully converted to python.py.
To obtain help on converter usage, options, and examples, type this command:
(.venv) PS C:\Users\user\pymapdl> pymapdl convert --help
Usage: pymapdl convert [OPTIONS] FILENAME_IN
PyMAPDL CLI tool for converting MAPDL scripts to PyMAPDL scripts.
USAGE:
...
(.venv) user@machine:~$ pymapdl convert --help
Usage: pymapdl convert [OPTIONS] FILENAME_IN
PyMAPDL CLI tool for converting MAPDL scripts to PyMAPDL scripts.
USAGE:
...
The pymapdl convert command uses the
convert_script() function.
Hence, this command accepts most of this function’s arguments.