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 |
|---|---|---|
|
|
One string |
|
|
One string |
|
|
Three numbers |
|
|
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 |
|
lines 26-28 |
|
lines 29-30 |
|
lines 31-32 |
|
lines 33-34 |
|