First pass at new command line API

[andreww]

Only changes the documentation. For discussion.

Other things to do:

• Agree command line CLI
• Implement changes
• Make "cats" a runnable programme (via install process)
• Update other documentation
• Add tests!

[abhidg]

Like the --scheduler option, will be easy to add others

[sadielbartholomew]

A major concern I have regarding the CLI API, ultimately of concern to the PR but perhaps not its current state which is more focused on valid arguments and their scope seemingly at present, which looks good to me, is the machine parsability and the human readability of the possible outputs.

Namely, I strongly suggest that we ensure that for whatever information that a user can request to output, whether a single figure (e.g. with this new suggested --quiet option which I like) or multiple statistics (e.g. run time plus carbon estimate, etc.), there is a means to provide that in a way which could be parsed by code, particularly as a recognised data serialisation format such as JSON or YAML or CSV, etc. (JSON seems most sensible without my having thought much about the choices, but we can discuss this).

We could even provide CLI options so that different formats can be output, e.g. JSON, CSV, since on the code side it is trivial to convert between those once we have constructed a standard format. Which makes me think that the --scheduler option shouldn't control the format, rather we have separate CLI option(s) to set that, e.g. -j for JSON and -y for YAML, or we can have an option for --format and custom formats for a given scheduler could be set as values, e.g. --format=json, --format=at, or similar.

If a --scheduler gets set, it could (and I think this would be useful) automatically set the --format to the appropriate format, but also pass, e.g. pipe, to the relevant scheduler. And for optimum human readability, we can have a dedicated option such as --format=simple or something.

I realise we generally we only be outputting a small number of pieces of information, but regardless having a standard output format means people can extract or forward that information as they wish.

So in short I am currently thinking we have a separate --format option to --schedule(r) option to initiate the actual scheduling, in which case we should allow the -- option so arguments can be passed onto the schedule rather than to CATS.

I also wonder if CATS would benefit from a separate formatting option to cover the datetime format supplied for run time and any other datetimes, since that piece of data in itself can be specified in a myriad of different ways, inside the overall data format of the output.

[andreww]

I like the idea of a --format and a --dateformat option to give us flexibility and allow us to output in a sensible data exchange format. I imagine --scheduler could just be a shorthand wrapper to a combination of other arguments to make the output play nice with other tools.

[abhidg]

@andreww is this ready to merge?

[andreww]

@abhidg - no, afraid not. Thus far it's just changing the documentation to describe what we want to happen (and that still needs further update following @sadielbartholomew's suggestion). Actually writing the code to make cats behave like this is still something that needs doing (and I don't think we should merge the documentation until it describes the code).

[colinsauze]

I've just had a play around with this and have a few questions about the way it now behaves:

1. you can specify both --jobinfo and --config, which one takes precedence? The documentation doesn't say. Should we warn if both are specified?
2. --command seems to be optional, is this intentional? In the old CLI we piped commands to At but that doesn't work now, so isn't this the only way to invoke a command?
3. The README, "Use with Schedulers" pages of the documentation and animated gif example don't match the new CLI format.
4. Should it be possible to run without the --scheduler option (currently it is)?
5. Does anything accept the JSON format that you get when --format is specified? We used to have an At friendly format with a simple start date, this is probably redundant now we have the --scheduler option, but if it was going to be possible then another format for --format would seem to be the right way to achieve that (or should it be a --dateformat? I'm a little confused as to the differentiation between the two).

[abhidg]

I've just had a play around with this and have a few questions about the way it now behaves:

1. you can specify both --jobinfo and --config, which one takes precedence? The documentation doesn't say. Should we warn if both are specified?

They control different things: --config is for TDP and specifying CPU/GPU models as well as the API and location (currently only one API) and --jobinfo is job specific info like amount of memory or number of CPUs used.

2. --command seems to be optional, is this intentional? In the old CLI we piped commands to At but that doesn't work now, so isn't this the only way to invoke a command?

I am good either way. One reasoning for keeping it optional is if the user wants to use CATS just to get the optimal time and not schedule.

3. The README, "Use with Schedulers" pages of the documentation and animated gif example don't match the new CLI format.

Will update them once the CLI is locked in!

4. Should it be possible to run without the --scheduler option (currently it is)?

Matter of taste. I am fine either way. We could also default to --scheduler=at such that --scheduler is actually optional and require a command.

5. Does anything accept the JSON format that you get when --format is specified? We used to have an At friendly format with a simple start date, this is probably redundant now we have the --scheduler option, but if it was going to be possible then another format for --format would seem to be the right way to achieve that (or should it be a --dateformat? I'm a little confused as to the differentiation between the two).

Nothing accepts the JSON format, it is more for piping to something like jq, which we can give examples of -- the --dateformat option controls the date formatting within --format output. The old behaviour of piping a command to at can be expressed for example as:

ls | at -t $(cats --loc OX1 -d 5 --dateformat='%Y%m%d%H%M' --format=json | jq -r '.carbonIntensityOptimal.start'

[tlestang]

I like this! Thanks for the work.