How to execute scripts?#

On this page we explain how the command-line interface of magnopy works.

A number of command-line scripts is defined in magnopy. Name of every single one of them starts with magnopy-. Examples on this page use magnopy-scenario as a placeholder for the script's name.

Getting help#

To display the help message and check what parameters are available for each script use

magnopy-scenario --help

See How to read help message to read more about help messages.

Arguments#

Every script expects some "arguments" (or "parameters" or "options") as an input. There are three types of arguments.

Positional arguments#

Only the value of an argument is expected. Script recognizes its meaning based on the position of that value within the command.

For example, assume that a script expects two positional arguments:

  • first argument with the name of the input file;

  • second argument with the name of the output file.

If you execute

magnopy-scenario input.txt output.txt

a script will use the file "input.txt" as an input file and write output to the "output.txt" file. However, if you execute

magnopy-scenario output.txt input.txt

then "output.txt" will be used as an input file and output will be written to the "input.txt" file.

Important

Order of positional arguments matters.

Keyword arguments with value#

Both the keyword and the value (one or several) of an argument are expected. The keyword is fixed and indicates the meaning of the argument. The value is the data that are passed to the script. Keyword arguments are given after positional ones. Order of keyword arguments does not matter.

For example, assume that a script expects an argument with the keyword --input-file, that requires a single value. If you execute

magnopy-scenario --input-file input.txt

then "--input-file" is a keyword and "input.txt" is the value.

Next, assume that a script expects an argument with the keyword --magnetic-fiel, that requires three values. If you execute

magnopy-scenario --magnetic-field 0 0 1

then "--magnetic-field" is a keyword and "0", "0" and "1" are the values. In this example the values describe components of the magnetic flux density \(B = (0, 0, 1)\).

Important

The keywords always start with "-" or "--".

Keyword arguments without value#

Only the keyword is expected. The keyword is fixed and indicates both the meaning of the argument and its value. This type of arguments is typically used when the argument has only two possible values: True or False. When such an argument is given to the script it switches the default value to its opposite.

For example, assume that a script expects an argument with the keyword --relative and default value False. If you execute

magnopy-scenario

a script will use False as a value for the argument with the keyword --relative. However, if you execute

magnopy-scenario --relative

then a script will use True as a value for the argument with the keyword --relative.

Important

The keywords always start with "-" or "--".

Long vs short keywords#

Majority of arguments in magnopy's scripts have two equivalent keywords: a long one and a short one. You are free to use either of them. The long version of the keyword starts with -- and the short version of the keyword starts with a single -.

The purpose of having both long and short keywords is to provide descriptive keywords (i. e. "long" ones) and to allow experienced users an option of using the short ones.

For example, assume that a set of arguments is defined for a script

Long keyword

Short keyword

Value

--input-file

-if

One string

--output-file

-of

One string

--magnetic-field

-mf

Three numbers

--relative

-r

No value

Then, two following commands are equivalent

magnopy-scenario --input-file input.txt --output-file output.txt --magnetic-field 0 0 1 --relative

magnopy-scenario -if input.txt -of output.txt -mf 0 0 1 -r

The first one is descriptive and the second one is compact.

Hint

You can use long keywords for some of the arguments and short ones for the other. The arguments are independent in this context.

How to read help message#

Assume that you executed a command

magnopy-scenario --help

and the script printed in the terminal the following

 1usage: magnopy-scenario [-h] -if FILENAME -of FILENAME [-mf h_x h_y h_z] [-r]
 2                        [-sv [S1 ...]]
 3
 4███╗   ███╗  █████╗   ██████╗  ███╗   ██╗  ██████╗  ██████╗  ██╗   ██╗
 5████╗ ████║ ██╔══██╗ ██╔════╝  ████╗  ██║ ██╔═══██╗ ██╔══██╗ ╚██╗ ██╔╝
 6██╔████╔██║ ███████║ ██║  ███╗ ██╔██╗ ██║ ██║   ██║ ██████╔╝  ╚████╔╝
 7██║╚██╔╝██║ ██╔══██║ ██║  ╚██║ ██║╚██╗██║ ██║   ██║ ██╔═══╝    ╚██╔╝
 8██║ ╚═╝ ██║ ██║  ██║ ╚██████╔╝ ██║ ╚████║ ╚██████╔╝ ██║         ██║
 9╚═╝     ╚═╝ ╚═╝  ╚═╝  ╚═════╝  ╚═╝  ╚═══╝  ╚═════╝  ╚═╝         ╚═╝
10                                                           ▄   ▄
11                      Version: major.minor.micro           █▀█▀█
12                Documentation: magnopy.org                 █▄█▄█
13             Release date: DAY MONTH YEAR                   ███   ▄▄
14                    License: GNU GPLv3                      ████ █  █
15          Copyright (C) 2023-CURRENT-YEAR  Magnopy Team     ████    █
16                                                            ▀▀▀▀▀▀▀▀
17
18This script is doing a thing, when provided a thing.
19
20options:
21  -h, --help            show this help message and exit
22  -if, --input-file     FILENAME
23                        Input file for the script.
24  -of, --output-file     FILENAME
25                        Output file for the script.
26  -mf, --magnetic-field H_X H_Y H_Z
27                        Vector of external magnetic field, given in the units
28                        of Tesla.
29  -r, --relative
30                        Whether to consider a thing to be a relative thing.
31  -sv, --spin-values [S1 ...]
32                        Spin values for the input thing.
33  -om, --optimization-mode {memory,speed}
34                        What kind of optimization shall be used.

A number of things can be deduced from this message.

Lines 1-2#

A draft of the command for using the script. Arguments that are enclosed in "[]" are optional, other arguments are mandatory. In this example --input-file and --output-file are mandatory and all other arguments are optional.

Lines 4-16#

Magnopy's logo and metadata.

  • Version of magnopy that is installed. For example "0.3.0", which would mean "0" major version, "3" minor version and "0" micro version;

  • Link to the web-site with documentation;

  • Release date;

  • License;

  • Copyright message;

Line 18#

Short description of what this script can do.

Lines 21-34#

Full list of all supported arguments and their description.

lines 22-23

  • "-if" is a short keyword of the argument.

  • "--input-file" is a long keyword of the argument.

  • "FILENAME" is a placeholder for its value. Substitute "FILENAME" by an actual value.

  • "Input file for the script." is a description of what this argument means.

lines 26-28

  • "-mf" is a short keyword of the argument.

  • "--magnetic-field" is a long keyword of the argument.

  • "H_X H_Y H_Z" are the placeholders for its values. Three placeholders indicate that this argument expects three values.

  • "Vector of external magnetic field, given in the units of Tesla." is a description of what this argument means.

lines 29-30

  • "-r" is a short keyword of the argument.

  • "--relative" is a long keyword of the argument.

  • There are no placeholder for the value, which means that this is a Keyword arguments without value.

  • "Whether to consider a thing to be a relative thing." is a description of what this argument means.

lines 31-32

  • "-sv" is a short keyword of the argument.

  • "--spin-values" is a long keyword of the argument.

  • "[S1 ...]" is a placeholder for the values. Brackets and "..." indicate that this argument expects several values. For example, substitute "[S1 ...]" by "1 0.5 1.5" to pass three values to this argument.

  • "Spin values for the input thing." is a description of what this argument means.

lines 33-34

  • "-om" is a short keyword of the argument.

  • "--optimization-mode" is a long keyword of the argument.

  • "{memory,speed}" is a placeholder for the values. Figure parenthesis indicate that one of the pre-defined values is expected. Use either --optimization-mode memory or --optimization-mode speed.

  • "What kind of optimization shall be used." is a description of what this argument means.