launch_mapdl

ansys.mapdl.core.launch_mapdl(exec_file=None, run_location=None, jobname='file', nproc=2, ram=None, mode=None, override=False, loglevel='ERROR', additional_switches='', start_timeout=120, port=None, cleanup_on_exit=True, start_instance=True, ip='127.0.0.1', clear_on_connect=True, log_apdl=False, verbose_mapdl=False, **kwargs)

Start MAPDL locally in gRPC mode.

Parameters

  • exec_file (str, optional) – The location of the MAPDL executable. Will use the cached location when left at the default None.

  • run_location (str, optional) – MAPDL working directory. Defaults to a temporary working directory. If directory doesn’t exist, will create one.

  • jobname (str, optional) – MAPDL jobname. Defaults to 'file'.

  • nproc (int, optional) – Number of processors. Defaults to 2.

  • ram (float, optional) – Fixed amount of memory to request for MAPDL. If None, then MAPDL will use as much as available on the host machine.

  • mode (str, optional) –

    Mode to launch MAPDL. Must be one of the following:

    • 'grpc'

    • 'corba'

    • 'console'

    The 'grpc' mode is available on ANSYS 2021R1 or newer and provides the best performance and stability. The 'corba' mode is available from v17.0 and newer and is given legacy support. This mode requires the additional ansys_corba module. Finally, the 'console' mode is for legacy use only Linux only prior to v17.0. This console mode is pending depreciation.

  • override (bool, optional) – Attempts to delete the lock file at the run_location. Useful when a prior MAPDL session has exited prematurely and the lock file has not been deleted.

  • loglevel (str, optional) – Sets which messages are printed to the console. 'INFO' prints out all ANSYS messages, 'WARNING` prints only messages containing ANSYS warnings, and 'ERROR' logs only error messages.

  • additional_switches (str, optional) –

    Additional switches for MAPDL, for example 'aa_r', the academic research license, would be added with:

    • additional_switches="-aa_r"

    Avoid adding switches like -i -o or -b as these are already included to start up the MAPDL server. See the notes section for additional details.

  • start_timeout (float, optional) – Maximum allowable time to connect to the MAPDL server.

  • port (int) – Port to launch MAPDL gRPC on. Final port will be the first port available after (or including) this port. Defaults to 50052. You can also override the default behavior of this keyword argument with the environment variable PYMAPDL_PORT=<VALID PORT>

  • custom_bin (str, optional) – Path to the MAPDL custom executable. On release 2020R2 on Linux, if None, will check to see if you have ansys.mapdl_bin installed and use that executable.

  • cleanup_on_exit (bool, optional) – Exit MAPDL when python exits or the mapdl Python instance is garbage collected.

  • start_instance (bool, optional) – When False, connect to an existing MAPDL instance at ip and port, which default to '127.0.0.1' at 50052. Otherwise, launch a local instance of MAPDL. You can also override the default behavior of this keyword argument with the environment variable PYMAPDL_START_INSTANCE=FALSE.

  • ip (bool, optional) – Used only when start_instance is False. Defaults to '127.0.0.1'. You can also override the default behavior of this keyword argument with the environment variable “PYMAPDL_IP=FALSE”.

  • clear_on_connect (bool, optional) – Used only when start_instance is False. Defaults to True, giving you a fresh environment when connecting to MAPDL.

  • log_apdl (str, optional) – Enables logging every APDL command to the local disk. This can be used to “record” all the commands that are sent to MAPDL via PyMAPDL so a script can be run within MAPDL without PyMAPDL.

  • remove_temp_files (bool, optional) – Removes temporary files on exit. Default False.

  • verbose_mapdl (bool, optional) – Enable printing of all output when launching and running MAPDL. This should be used for debugging only as output can be tracked within pymapdl. Default False.

Examples

Launch MAPDL using the best protocol.

>>> from ansys.mapdl.core import launch_mapdl
>>> mapdl = launch_mapdl()

Run MAPDL with shared memory parallel and specify the location of the ansys binary.

>>> exec_file = 'C:/Program Files/ANSYS Inc/v201/ansys/bin/win64/ANSYS201.exe'
>>> mapdl = launch_mapdl(exec_file, additional_switches='-smp')

Connect to an existing instance of MAPDL at IP 192.168.1.30 and port 50001. This is only available using the latest 'grpc' mode.

>>> mapdl = launch_mapdl(start_instance=False, ip='192.168.1.30',
                         port=50001)

Force the usage of the CORBA protocol.

>>> mapdl = launch_mapdl(mode='corba')

Run MAPDL using the console mode (available only on Linux).

>>> mapdl = launch_mapdl('/ansys_inc/v194/ansys/bin/ansys194',
                          mode='console')

Notes

These are the MAPDL switch options as of 2020R2 applicable for running MAPDL as a service via gRPC. Excluded switches such as "-j" either not applicable or are set via keyword arguments.

-acc <device>Enables the use of GPU hardware. See GPU

Accelerator Capability in the Parallel Processing Guide for more information.

-amfgEnables the additive manufacturing capability. Requires

an additive manufacturing license. For general information about this feature, see AM Process Simulation in ANSYS Workbench.

-ansexe <executable>Activates a custom mechanical APDL executable.

In the ANSYS Workbench environment, activates a custom Mechanical APDL executable.

-custom <executable>Calls a custom Mechanical APDL executable

See Running Your Custom Executable in the Programmer’s Reference for more information.

-db valueInitial memory allocation

Defines the portion of workspace (memory) to be used as the initial allocation for the database. The default is 1024 MB. Specify a negative number to force a fixed size throughout the run; useful on small memory systems.

-disEnables Distributed ANSYS

See the Parallel Processing Guide for more information.

-dvtEnables ANSYS DesignXplorer advanced task (add-on).

Requires DesignXplorer.

-l <language>Specifies a language file to use other than English

This option is valid only if you have a translated message file in an appropriately named subdirectory in /ansys_inc/v201/ansys/docu or Program Files\ANSYS\Inc\V201\ANSYS\docu

-m <workspace>Specifies the total size of the workspace

Workspace (memory) in megabytes used for the initial allocation. If you omit the -m option, the default is 2 GB (2048 MB). Specify a negative number to force a fixed size throughout the run.

-machines <IP>Specifies the distributed machines

Machines on which to run a Distributed ANSYS analysis. See Starting Distributed ANSYS in the Parallel Processing Guide for more information.

-mpi <value>Specifies the type of MPI to use.

See the Parallel Processing Guide for more information.

-mpifile <appfile>Specifies an existing MPI file

Specifies an existing MPI file (appfile) to be used in a Distributed ANSYS run. See Using MPI Files in the Parallel Processing Guide for more information.

-na <value>: Specifies the number of GPU accelerator devices

Number of GPU devices per machine or compute node when running with the GPU accelerator feature. See GPU Accelerator Capability in the Parallel Processing Guide for more information.

-name <value>Defines Mechanical APDL parameters

Set mechanical APDL parameters at program start-up. The parameter name must be at least two characters long. For details about parameters, see the ANSYS Parametric Design Language Guide.

-p <productname>ANSYS session product

Defines the ANSYS session product that will run during the session. For more detailed information about the -p option, see Selecting an ANSYS Product via the Command Line.

-ppf <license feature name>HPC license

Specifies which HPC license to use during a parallel processing run. See HPC Licensing in the Parallel Processing Guide for more information.

-smpEnables shared-memory parallelism.

See the Parallel Processing Guide for more information.