A CLI to automate mundane tasks with Idefix
Project description
idefix_cli:idfx
This is a CLI helper tool for Idefix, named idfx. idfx gathers and automates
boring and repetetive tasks such as setup and cleanup in a single tool.
Warning: Idefix itself is not publicly available yet.
Installation
stable
It is recommended to install this tool in isolation with pipx as
$ pipx install idefix_cli
Otherwise, the simplest way to install the latest stable version is
$ python3 -m pip install idefix_cli
bleeding-edge
From the top level of the repo, run
$ python3 -m pip install -u -e .
Note that most idfx commands explicitly require that the env variable $IDEFIX_DIR be
set.
Internal documentation
The following contains usage examples. Get a complete description of available options with
$ idfx --help
Likewise, get help for each command therein as, for instance
$ idfx run --help
Commands
idfx setup
idfx setupis based ofidefix/configure.pyand aims to replace it.
idfx setup creates a valid Makefile at the specified location and with the speficied
parameters (CPU/GPU ? HD/MHD ? ... set idfx setup --help).
$ idfx setup . -mhd -gpu
idfx setup also takes a --make (aliased to --compile) flag which will run
$ make -j <N_CPUS>
where <N_CPUS> is the number of cpus available (up to 8).
idfx run
idfx run runs the Idefix problem found at the specified location. It is mostly useful
run tests problems sequentially for very short periods.
Note that this command will fail if neither idefix or Makefile are found in the
specified directory. In case only the Makefile is present, this command will compile the
program first.
idfx runis not a complete wrapper around theidefixexecutable. This means that if you need to pass additional arguments toidefixother than-i, you should run it directly.
minimal example: run a test sequentially
$ idfx run $IDEFIX_DIR/test/HD/KHI
The default behaviour is to use idefix.ini contained in the specified directory. If you
want to run a different one, use -i/--inifile
$ idfx run . -i myconf.ini
Note that idfx run looks for the inifile relative to the cwd, and then relative to
the specified directory.
running a shorter version of a problem
Use the --duration and --time-step arguments to run a modified version of a base
inifile.
$ idfx run . --duration 1e-4
The patched copy will be save to a
.ini_file with a unique identifier (UUID). Those files are cleaned with other withidfx clean --all
Note that --time-step maps to Idefix's inifile TimeIntegrator.first_dt.
Use --one-step/--one to run a single time step (total simulation time equates to the
first time step).
The length of the time step can be adjusted in combination with --time-step, however,
--one-step is incompatible with --duration.
$ idfx run . --one
is a shortcut for
$ idfx run . --duration x --time-step x
where x, is the existing value found in the inifile.
IO operations for inifiles
idfx read
Read an Idefix inifile and print the resulting dictionnary to stdout in a json parsable format. This is useful to inspect inifiles programatically in combination with tools like jq
$ idfx read $IDEFIX_DIR/test/HD/KHI/idefix.ini | jq '.Output.vtk' --compact-output
[0.01,-1,"single_file"]
By default, the ouptut of idfx read is flat. Optionnaly, you can use --indent <N> to
improve human-readability.
idfx write
Conversely, idfx write converts from json formatted strings to Idefix inifile format
$ idfx write save.ini $(cat save.json)
arbitrary patching
idfx read and idfx write methods can be combined with jq to arbitrarily patch an inifile
$ idfx read test/HD/KHI/idefix.ini | jq .TimeIntegrator.CFL=1e6 | idfx write idefix_patched.ini
idfx clean
Removes generated files.
$ idfx clean .
By default only intermediate C++ (*.o, *.host and *.cuda) files are cleaned.
To also remove Makefile, idefix executables and *.ini_ files generated by idfx,
run
$ idfx clean . --all
idfx clean also accepts a --dry-run/--dry flag. If this flag is passed
then the list of files that would be deleted is printed.
idfx stamp
Prints key data for reproduction and development to stdout.
$ idfx stamp
v0.5
daff799bb64b0993f058f50779873d594376d5bf
lesurg
f-dahu
Sat Jan 16 16:15:28 2021
Which is roughly equivalent (and slightly more portable) to
$ cd $IDEFIX_DIR \
&& git describe --tags \
&& cd - > /dev/null \
&& date \
&& hostname \
&& echo $USER
Additionnally, one can get the underlying data in json-serializable format
$ idfx stamp --json
{
"tag": "v0.5",
"sha": "daff799bb64b0993f058f50779873d594376d5bf",
"user": "glesur"
"host": "f-dahu",
"date": "Sat Jan 16 16:15:54 2021",
}
This is helpful to quickly store important metadata next to one's datafiles. The git tag may be of critical value for reproductability, especially when bugs in Idefix are found after simulations are run, like so
$ idfx stamp --json > metadata.json
Contribution guidelines
We use the pre-commit framework to automatically lint for code style and common pitfals.
Before you commit to your local copy of the repo, please run this from the top level
$ python3 -m pip install -u -e .[dev]
$ pre-commit install
Testing
We use the pytest framework to test idfx's
internal components. The test suite can be run from the top level with a simple pytest
invocation.
$ pytest
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file idefix_cli-0.1.3.tar.gz.
File metadata
- Download URL: idefix_cli-0.1.3.tar.gz
- Upload date:
- Size: 26.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | e476374418928fd73dede5d3b12fb5210b477b35e644586c46544b151f6deb1e |
|
| MD5 | 0d0d43be8f84ce57405c455f16572ab6 |
|
| BLAKE2b-256 | 64d942e69a49c4bba95d4e3a2391fbf774b95ea4d6c7a5eab14f0843ccf9301e |
File details
Details for the file idefix_cli-0.1.3-py3-none-any.whl.
File metadata
- Download URL: idefix_cli-0.1.3-py3-none-any.whl
- Upload date:
- Size: 25.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 42da38e3b4b3dca4686fc1900040f7533beab171b2398e1e3842d8a8aab03753 |
|
| MD5 | e85b7a2bcdf960a1cbf9762dee9c6bf4 |
|
| BLAKE2b-256 | 4ae762598c492cc5b540bb630d8a6ffbb81db1cd948485030d62184ed6cf9cfa |
