{ "cells": [ { "cell_type": "markdown", "id": "ac862163", "metadata": {}, "source": [ "(cmdline)=\n", "\n", "# Command-line tools\n", "\n", "In addition to the Python API, flatspin comes with a set of powerful command-line tools.\n", "These are installed automatically as part of the flatspin package.\n", "\n", "If you find that the commands are not available in your shell automatically, you may need to modify your `PATH` variable.\n", "The location of the command-line tools varies based on the operating system and installation method.\n", "\n", "If you installed flatspin in your home directory (using `pip install --user`):\n", "\n", "```bash\n", "export PATH=$PATH:$HOME/.local/bin\n", "```\n", "\n", "The command-line tools can be understood from the flatspin architecture:\n", "\n", "![flatspin architecture](images/architecture.svg)\n", "\n", "In the figure, the arrows indicate data flow between the components:\n", "1. The [input encoder](encoders) translates input to a field protocol (series of external fields).\n", "2. The *runner* perturbs the [ASI model](model) according to the field protocol, and saves the results.\n", "3. The results are stored in a [dataset](datasets)\n", "4. Analysis tools read and process the [dataset](datasets).\n", "\n", "```{note}\n", "A good understanding of the concepts introduced in the rest of this User Guide is beneficial to effectively use the command-line tools.\n", "```" ] }, { "cell_type": "markdown", "id": "e125c65b", "metadata": {}, "source": [ "(cmdline-running)=\n", "## Running simulations\n", "\n", "flatspin simulations can be run directly from the command line, using the commands [`flatspin-run`](flatspin-run) and [`flatspin-run-sweep`](flatspin-run-sweep).\n", "These tools were designed to be flexible enough to allow for a range of different simulation scenarios.\n", "\n", "Some notable features include:\n", "\n", "- Results are stored in the standard [dataset format](dataset) for later analysis.\n", "- All simulation parameters can be specified from the command-line.\n", "- [Input encoders](encoders) are used to define the external field.\n", "- Parameter sweeps can be defined to run many simulations in one go.\n", "- Simulations may be run in parallel on a compute cluster." ] }, { "cell_type": "markdown", "id": "50152994", "metadata": {}, "source": [ "(cmdline-flatspin-run)=\n", "### [`flatspin-run`](flatspin-run)\n", "\n", "To run a single flatspin simulation, use [`flatspin-run`](flatspin-run).\n", "\n", "Let us start with a simple example:\n", "\n", "(cmdline-run-simple)=\n", "```bash\n", "flatspin-run -o /tmp/flatspin/myrun -m SquareSpinIceClosed \\\n", " -e Triangle -p H=100e-3 -p phase=-90 -p phi=30 -p periods=1\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "ad4b0096", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "rm -rf /tmp/flatspin/myrun\n", "flatspin-run -o /tmp/flatspin/myrun -m SquareSpinIceClosed \\\n", " -e Triangle -p H=100e-3 -p phase=-90 -p phi=30 -p periods=1" ] }, { "cell_type": "markdown", "id": "fa592756", "metadata": {}, "source": [ "The `-o/--basepath` argument specifies the directory where simulation results will be stored as a [dataset](dataset).\n", "This directory should not already exist, and will be automatically created by [`flatspin-run`](flatspin-run).\n", "\n", "The `-m/--model` argument refers to the [model class](model) to use.\n", "You may also specify your own model class by providing the full module path, e.g., `-m mymodels.MySpinIce`.\n", "\n", "The `-e/--encoder` argument specifies the [input encoder](encoders) to use for defining the field protocol.\n", "In the example, the `Triangle` encoder is used which results in a linear ramped external field.\n", "For a list of available encoders, see `flatspin-run --list-encoders`.\n", "You may also specify your own encoder class by providing the full module path, e.g., `-e myencoders.MyEncoder`.\n", "\n", "The `-p/--param` arguments are parameters to the model, the runner and the encoder:\n", "* `-p H=100e-3` sets the amplitude of the external field to 100 mT\n", "* `-p phase=-90` sets the phase of the triangle wave to -90°\n", "* `-p phi=30` sets the angle of the external field to 30°\n", "* `-p periods=1` sets the number of field cycles to 1\n", "\n", "For a list of available parameters, append `--list-params` to the [`flatspin-run`](flatspin-run) command." ] }, { "cell_type": "markdown", "id": "b33b5ca8", "metadata": {}, "source": [ "### The runner\n", "\n", "The {func}`runner ` is responsible for running the simulation.\n", "In simplified pseudocode, the runner does the following:\n", "\n", "```\n", "model = ModelClass(model_params)\n", "encoder = EncoderClass(encoder_params)\n", "h_ext = encoder(input)\n", "for h in h_ext:\n", " model.set_h_ext(h)\n", " model.relax()\n", " if should_sample:\n", " record current state of the model\n", "save recorded states as tables in the dataset\n", "```\n", "\n", "As you can see, the external field is what drives the simulation.\n", "Each value of `h_ext` is immediately followed by a call to {func}`model.relax() `, which flips any spins in response to the new field value.\n", "\n", "(cmdline-params)=\n", "### Parameters\n", "\n", "The parameters passed by the `-p/--param` arguments are consumed in the following order:\n", "1. The model class (passed to the constructor)\n", "2. The runner (passed to {func}`flatspin.runner.run`)\n", "3. The encoder class (passed to {func}`Encoder.set_params() `\n", "\n", "It is assumed that there is never overlap between the parameter names for the model, runner and encoders.\n", "\n", "For a list of available parameters, append `--list-params` to the [`flatspin-run`](flatspin-run) command.\n", "Documentation for each parameter can be found in the {class}`model class `, the {func}`runner ` and the corresponding encoder class {mod}`flatspin.encoder`.\n", "\n", "Parameter values are evaluated as Python code (using [eval](https://docs.python.org/3/library/functions.html#eval)).\n", "Values may use numpy code, e.g., `-p param=np.random.rand()`.\n", "Some additional utility functions are also available, see {data}`flatspin.cmdline.param_globals`.\n", "\n", "### Input\n", "\n", "The `input` to the encoder may provided in a few different ways:\n", "1. Passed directly as an array: `-p input=[0.3, 0.5, 1.0]`\n", "2. Created indirectly: `-p periods=P` which is short-hand for `-p input=[1]*P`\n", "3. Loaded from file: `-p input=myinput.csv` which is read with {func}`read_table() `.\n", " To select a specific column to use: `-p input_key=column_name`.\n", "\n", "### Selecting the sample rate: `spp` and `timesteps`\n", "\n", "The [encoder](encoders) may produce many `h_ext` values for each `input` value.\n", "The number of `h_ext` values is typically controlled by the `timesteps` [encoder parameter](encoders-params).\n", "For example, the `Triangle` encoder uses `timesteps=100` by default, meaning there will be 100 `h_ext` field values per `input` value.\n", "\n", "The `spp` runner parameter determines how often the state of the model should be sampled (and saved).\n", "The parameter name `spp` is an abbreviation for *samples per period*, and specifies the number samples per input period.\n", "In the `Triangle` example, we can use `-p spp=100` to sample the model state after every `h_ext` value, or\n", "`-p spp=50` to sample every other `h_ext` value, or `-p spp=1` to sample once for each `input` value (sampled at the beginning of the input).\n", "\n", "Some care must be taken when choosing `spp` such that it is compatible with `timesteps`.\n", "It is the users responsibility to ensure that `spp` evenly divides `timesteps` (a warning is generated if it does not).\n", "\n", "(cmdline-params-t)=\n", "### Time-varying parameters\n", "\n", "Some model parameters may also be modified dynamically over time.\n", "Time-varying parameters can be defined by adding a `_t` suffix to the parameter name, for example:\n", "\n", "```bash\n", "flatspin-run ... -p temperature_t='[400, 350, 300]'\n", "```\n", "\n", "will create a time-varying temperature with three values.\n", "The length of all time-varying parameters *must match the length of the `input`*.\n", "\n", "Currently, the following time-varying parameters are supported:\n", "`alpha_t`, `hc_t`, `m_therm_t`, `spin_t`, `temperature_t`, `therm_timescale_t`, `threshold_t`\n", "The external field must be created using the input encoder, i.e., `h_ext_t` is not allowed." ] }, { "cell_type": "markdown", "id": "01ca5a5e", "metadata": {}, "source": [ "(cmdline-flatspin-run-sweep)=\n", "### [`flatspin-run-sweep`](flatspin-run-sweep)\n", "\n", "Often we wish to explore how an ASI changes behavior under different parameters.\n", "Parameter sweeps is a simple and effective way to systematically explore the effect of one or multiple parameters.\n", "\n", "[`flatspin-run-sweep`](flatspin-run-sweep) accepts a list of parameters to sweep, and runs a series of flatspin simulations using the given parameter values.\n", "Continuing our [simple example](cmdline-run-simple), we sweep the field strength `H`:\n", "\n", "(cmdline-run-sweep)=\n", "```bash\n", "flatspin-run-sweep -o /tmp/flatspin/mysweep -m SquareSpinIceClosed \\\n", " -e Triangle -p phase=-90 -phi=30 -p periods=1 \\\n", " -s 'H=[80e-3, 84e-3, 88e-3, 92e-3]'\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "3af8066f", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "rm -rf /tmp/flatspin/mysweep\n", "flatspin-run-sweep -o /tmp/flatspin/mysweep -m SquareSpinIceClosed \\\n", " -e Triangle -p phase=-90 -p phi=30 -p periods=1 \\\n", " -s 'H=[80e-3, 84e-3, 88e-3, 92e-3]'" ] }, { "cell_type": "markdown", "id": "3051e6c4", "metadata": {}, "source": [ "The `-s/--sweep` argument in the above command specifies a sweep of the parameter `H` with a list of values ranging from 80 mT to 92 mT.\n", "\n", "Note how the invocation of [`flatspin-run-sweep`](flatspin-run-sweep) is identical to [`flatspin-run`](flatspin-run), with the addition of `-s/--sweep`.\n", "\n", "Multiple parameters may be swept by providing multiple `-s/--sweep` arguments, in which case all combinations of parameter values will be swept.\n", "\n", "For example, the command:\n", "\n", "```bash\n", "flatspin-run-sweep ... -s 'phi=[0, 30, 45]' -s 'H=[80e-3, 84e-3, 88e-3, 92e-3]'\n", "```\n", "\n", "would sweep the two parameters `phi` and `H`, starting with `phi=0, H=80e-3`, then `phi=0, H=84e-3`, and so on until finally `phi=45, H=92e-3` is reached.\n", "The above sweep would result in a total of 12 flatspin runs.\n", "\n", "In addition, each run may be repeated `N` times with `-n/--repeat N`.\n", "This is useful when simulating stochastic systems, e.g., with [disorder](model-hc) or [thermal fields](fields-thermal) enabled." ] }, { "cell_type": "markdown", "id": "89368220", "metadata": {}, "source": [ "### Distributed running\n", "\n", "As the number of parameters grow, it may be beneficial to distribute the simulations onto a compute cluster to run them in parallel.\n", "Distributed running is supported both by [`flatspin-run`](flatspin-run) and [`flatspin-run-sweep`](flatspin-run-sweep) with the `-r dist` argument.\n", "\n", "flatspin uses [SLURM](https://slurm.schedmd.com/) to submit cluster jobs.\n", "Currently you need to edit the file `flatspin.slurm.sh` to configure flatspin for your particular cluster.\n", "Other job schedulers should be possible with minimal code changes." ] }, { "cell_type": "markdown", "id": "84b0d35d", "metadata": {}, "source": [ "## Analysis tools\n", "\n", "A set of analysis tools are included in flatspin, which all operate on datasets such as those produced by [`flatspin-run`](flatspin-run) and [`flatspin-run-sweep`](flatspin-run-sweep)." ] }, { "cell_type": "markdown", "id": "36c6a398", "metadata": {}, "source": [ "### [`flatspin-inspect`](flatspin-inspect)\n", "\n", "[`flatspin-inspect`](flatspin-inspect) is a handy tool to quickly get an overview of the contents of a dataset.\n", "\n", "For example, let us have a look at the [sweep we created above](cmdline-run-sweep):\n", "\n", "```bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -l\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "202582c4", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -l" ] }, { "cell_type": "markdown", "id": "af18d728", "metadata": {}, "source": [ "The output of `flatspin-inspect -l` consists of three parts:\n", "\n", "1. Parameter listing `params`: A list of all the parameters used in the run.\n", " Notice how this listing contains parameters that were not specified in the [`flatspin-run-sweep`](flatspin-run-sweep) command.\n", " These parameters record the default values at the dataset creation time.\n", "2. Information `info`: Miscellaneous information about the run, including the full [`flatspin-run-sweep`](flatspin-run-sweep) command.\n", "3. The `index` of the runs in the dataset: the index contains one column for each swept parameter.\n", "\n", "```{tip}\n", "If the `-b/--datapath` argument is omitted, the flatspin analysis tools will look for a dataset in the current working directory.\n", "```" ] }, { "cell_type": "markdown", "id": "c50fc4ae", "metadata": {}, "source": [ "### Tables included in a run\n", "Let us have a look at what tables are available within each run:\n", "\n", "```bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "3a831dbf", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep" ] }, { "cell_type": "markdown", "id": "034e5c2f", "metadata": {}, "source": [ "From the output above, we can see that each run in the dataset contains quite a few tables.\n", "Tables marked with a `[t]` contain time-dependent data.\n", "Below is a short description of the tables, with references to the releated model attributes or methods.\n", "\n", "| Table | Description |\n", "| ---------- | ----------- |\n", "| `energy` | [Energy](analysis-energy) over time |\n", "| `geometry` | [Position and angle](model-geometry) of each spin |\n", "| `h_ext` | [External field](fields-external) over time |\n", "| `h_therm` | [Thermal field](fields-thermal) over time (if `temperature > 0`) |\n", "| `hc` | [Coercive fields](model-hc) of each spin |\n", "| `init` | [Initial state](model-spin) of each spin |\n", "| `input` | [Input](encoders-input) over time |\n", "| `mag` | [Magnetization vectors](model-vectors) over time |\n", "| `params` | [Parameter](cmdline-params) listing |\n", "| `params_t` | [Time-varying parameters](cmdline-params-t) over time (if any) |\n", "| `spin` | [Spin state](model-spin) over time |\n", "| `stats` | Run statistics |\n", "| `steps` | Cumulative number of [steps](dynamics-step) over time |" ] }, { "cell_type": "markdown", "id": "01f1eb52", "metadata": {}, "source": [ "### Subset and filter\n", "\n", "Just like the [flatspin dataset API](dataset-subset), we can select a subset of the dataset with `-i/--subset` or `-s/--filter`:\n", "\n", "```bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -i 1:2\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "ced218ee", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -i 1:2" ] }, { "cell_type": "markdown", "id": "7b264535", "metadata": {}, "source": [ "```bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -s H=0.084\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "19b784c8", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-inspect -b /tmp/flatspin/mysweep -s H=0.084" ] }, { "cell_type": "markdown", "id": "bf3df3a6", "metadata": {}, "source": [ "In fact, all the flatspin analysis tools support a common set of command-line options, such as `-i/--subset`, `-s/--filter` and `-l/--list`." ] }, { "cell_type": "markdown", "id": "13717622", "metadata": {}, "source": [ "### [`flatspin-plot`](flatspin-plot)\n", "\n", "For quickly plotting data from a dataset, [`flatspin-plot`](flatspin-plot) is your friend.\n", "\n", "Let us plot the external field over time from the `myrun` dataset created earlier:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/myrun -x t -y h_ext\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "e0aa438b", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "mkdir -p images/generated\n", "flatspin-plot -b /tmp/flatspin/myrun -x t -y h_ext -o images/generated/myrun_h_ext.svg" ] }, { "cell_type": "markdown", "id": "e31c7779", "metadata": {}, "source": [ "![](images/generated/myrun_h_ext.svg)" ] }, { "cell_type": "markdown", "id": "b0858988", "metadata": {}, "source": [ "Similarly, we can plot data from multiple runs:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -y h_ext\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "f2b72f50", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -y h_ext -o images/generated/mysweep_h_ext.svg" ] }, { "cell_type": "markdown", "id": "de0664e4", "metadata": {}, "source": [ "![](images/generated/mysweep_h_ext.svg)" ] }, { "cell_type": "markdown", "id": "7011b3d8", "metadata": {}, "source": [ "Plot everything from a given table with `-g/--table`:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/myrun -x t -g energy\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "0d4a955b", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-plot -b /tmp/flatspin/myrun -x t -g energy -o images/generated/myrun_energy.svg" ] }, { "cell_type": "markdown", "id": "7c2d53d5", "metadata": {}, "source": [ "![](images/generated/myrun_energy.svg)" ] }, { "cell_type": "markdown", "id": "d4d24bbc", "metadata": {}, "source": [ "Rudimentary functions are also supported, e.g., to sum of all the spins over time:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -y 's=sum(spin*)'\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "891b3ed7", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -y 's=sum(spin*)' -o images/generated/mysweep_spin.svg" ] }, { "cell_type": "markdown", "id": "8ab473f0", "metadata": {}, "source": [ "![](images/generated/mysweep_spin.svg)" ] }, { "cell_type": "markdown", "id": "7fd47215", "metadata": {}, "source": [ "... or the same data plotted as a heatmap:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -z 's=sum(spin*)'\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "5a116e05", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-plot -b /tmp/flatspin/mysweep -k H -x t -z 's=sum(spin*)' -o images/generated/mysweep_spin_heatmap.svg" ] }, { "cell_type": "markdown", "id": "0858e7e2", "metadata": {}, "source": [ "![](images/generated/mysweep_spin_heatmap.svg)" ] }, { "cell_type": "markdown", "id": "06be0ccd", "metadata": {}, "source": [ "Arbitrary columns may be used on the x-axis:\n", "\n", "```bash\n", "flatspin-plot -b /tmp/flatspin/myrun -x 'mx=sum(mag*x)' -y 'my=sum(mag*y)'\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "143f2144", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-plot -b /tmp/flatspin/myrun -x 'mx=sum(mag*x)' -y 'my=sum(mag*y)' -o images/generated/myrun_mxmy.svg" ] }, { "cell_type": "markdown", "id": "6c98c384", "metadata": {}, "source": [ "![](images/generated/myrun_mxmy.svg)" ] }, { "cell_type": "markdown", "id": "4f63a55b", "metadata": {}, "source": [ "See `flatspin-plot --help` for a full list of options." ] }, { "cell_type": "markdown", "id": "59aee4ca", "metadata": {}, "source": [ "### [`flatspin-vectors`](flatspin-vectors)\n", "\n", "Use [`flatspin-vectors`](flatspin-vectors) to animate spin vectors over time.\n", "The time steps to include can be limited using `-t start:stop:step`.\n", "In the command below we include all time steps, and draw vectors as arrows.\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 --arrows\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "4604800b", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 --arrows -o images/generated/myrun.gif" ] }, { "cell_type": "markdown", "id": "9183c2db", "metadata": {}, "source": [ "```{image} images/generated/myrun.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "b4d8130c", "metadata": {}, "source": [ "It is often useful to compare results from multiple runs.\n", "When the dataset contains multiple runs, [`flatspin-vectors`](flatspin-vectors) animates them side by side in a *montage*:\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/mysweep -t ::1 --arrows\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "d993f2e1", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/mysweep -t ::1 --arrows -o images/generated/mysweep.gif" ] }, { "cell_type": "markdown", "id": "b3d7e44b", "metadata": {}, "source": [ "```{image} images/generated/mysweep.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "3cbd0a04", "metadata": {}, "source": [ "It is also possible to create a *montage over time*, where each image corresponds to the same run at different points in time.\n", "Montage over time is enabled with `-a/--animate-dataset`.\n", "When the images become small, it is a good idea to turn off `--arrows`, which results in a grid based visualization instead.\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "acaff54d", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a -o images/generated/myrun_time.gif" ] }, { "cell_type": "markdown", "id": "e341fca2", "metadata": {}, "source": [ "```{image} images/generated/myrun_time.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "56761c03", "metadata": {}, "source": [ "By default, [`flatspin-vectors`](flatspin-vectors) animates the spin vectors, but other quantities can be specified with `-q/--quantity`:\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 --arrows -q h_ext\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "0a29d989", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 --arrows -q h_ext -o images/generated/myrun_h_ext.gif" ] }, { "cell_type": "markdown", "id": "f9555e01", "metadata": {}, "source": [ "```{image} images/generated/myrun_h_ext.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "244240ea", "metadata": {}, "source": [ "#### Apply a grid\n", "A [grid](analysis-grid) may be applied to the vectors to produce an aggregate view with `-g/--grid`.\n", "Below we apply a `2x2` grid and sum the vectors in each grid cell:\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a -g 2\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "4f6fdf9a", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a -g 2 -o images/generated/myrun_grid.gif" ] }, { "cell_type": "markdown", "id": "e24caa0f", "metadata": {}, "source": [ "```{image} images/generated/myrun_grid.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "a938296a", "metadata": {}, "source": [ "The different color shades in the images above are caused by each grid cell having a different number of spins.\n", "For the square closed geometry, we can obtain vertex magnetization by first cropping away the spins at the edges (`-c/--crop 1`), and then apply a sliding 3x3 window with a step size of 2 (`-w/--window 3 2`):\n", "\n", "```bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a -c 1 -w 3 2\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "6af2a76e", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "%%bash\n", "flatspin-vectors -b /tmp/flatspin/myrun -t ::1 -a -c 1 -w 3 2 -o images/generated/myrun_window.gif" ] }, { "cell_type": "markdown", "id": "8c7952d9", "metadata": {}, "source": [ "```{image} images/generated/myrun_window.gif\n", ":width: 480px\n", "```" ] }, { "cell_type": "markdown", "id": "170a0fcc", "metadata": {}, "source": [ "For other geometries, the above windowing trick may not be applicable to find vertices.\n", "The [`flatspin-vertices`](flatspin-vertices) tool is similar to [`flatspin-vectors`](flatspin-vectors), but employs [vertex detection](analysis-vertex-detection) to correctly visualize vertex magnetization for all the included geometries." ] }, { "cell_type": "markdown", "id": "ef2b79d7", "metadata": {}, "source": [ "## Other tools\n", "\n", "In this guide, we have introduced some of the most commonly used command-line tools in flatspin.\n", "Several other tools are included, available with the [`flatspin-`](flatspin-) prefix.\n", "For a full list of command-line tools, see [](reference/cmdline)." ] } ], "metadata": { "jupytext": { "formats": "md:myst", "text_representation": { "extension": ".md", "format_name": "myst", "format_version": 0.13, "jupytext_version": "1.11.5" } }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.10" }, "source_map": [ 13, 45, 61, 76, 83, 104, 182, 200, 208, 228, 239, 245, 257, 262, 276, 285, 290, 312, 322, 327, 333, 338, 342, 354, 360, 364, 372, 377, 381, 389, 394, 398, 406, 411, 415, 423, 428, 432, 440, 445, 449, 453, 465, 470, 476, 485, 490, 496, 506, 511, 517, 525, 530, 536, 546, 551, 557, 566, 571, 577, 582 ] }, "nbformat": 4, "nbformat_minor": 5 }