Change experiment_name to apparatus_name in labconfig

[rpanderson]

The term 'experiment' is overused and currently classifies at least:

• A given labscript (experiment) Python script (although this is strictly referred to e.g. in the [experiment!] shot file as the script_basename); and
• The apparatus that this experiment is executed on.

This proposal would see the experiment_name keyword renamed to apparatus_name in labconfig and downstream code, which is a better acknowledgement of the intended classification (which was only termed 'experiment' owing to this being a colloquially synonymous with 'apparatus').

This would mostly affect the [DEFAULT] labconfig section, i.e.

[DEFAULT]
apparatus_name = default_apparatus
shared_drive = C:
experiment_shot_storage = %(shared_drive)s\Experiments\%(apparatus_name)s
userlib=%(labscript_suite)s\userlib
pythonlib = %(userlib)s\pythonlib
labscriptlib = %(userlib)s\labscriptlib\%(apparatus_name)s
analysislib = %(userlib)s\analysislib\%(apparatus_name)s
app_saved_configs = %(labscript_suite)s\app_saved_configs\%(apparatus_name)s

The impetus for this proposal came from working example code that I am currently developing (so that the entire suite will work out-of-the-box), which I'd like to name, e.g. example_experiment.py. which runs on default_apparatus (or example_apparatus), etc. Otherwise you have example_experiment.py running on default_experiment which is ambiguous and exposes this mis/over-use of terminology.

[chrisjbillington]

I'm not sure it maps to apparatus definitively. At the moment you can basically change 'experiment_name' within the same lab and have apps auto-load different configs, BLACS load a different connection table, etc. This allows you to switch between different experiments on the same apparatus.

This is a not super-often-used feature, to be sure - mostly people do indeed use this to map to apparatus in order to keep their data from different labs separate on a shared drive. Though in the chip lab we were switching 'experiments' on a near-daily basis as work on different projects proceeded in parallel. We were sharing a connection table and manually switching out all the config in runmanager/lyse, but changing the experiment_name would likely have been a good alternative. So that's an argument in favour of it being considered the name of the experiment instead of the apparatus.

The overloading of terminology is unfortunate - that one 'experiment' (a broad line of investigation) has potentially many 'experiment scripts' corresponding to it.

The fact that a connection table must represent the state of the lab and is thus coupled to hardware, however, does mean it's pretty pointless to switch connection tables by changing this variable though. The connection table is pretty much a one-to-one mapping to an apparatus. If you are going to switch experiments you would either be duplicating the connection table, or storing it at a filepath without experiment_name in its path, which would then potentially collide with other labs sharing a shared drive. So that's an argument in favour of the variable naming the apparatus. Perhaps in the chip lab, sharing the connection table despite having different 'experiments' would have been more of a pain in the neck than just loading runmanager and lyse configs (and potentially a BLACS front panel) every few days.

All considered I think I lean in favour of renaming it.

[rpanderson]

I can see how changing the value of experiment_name in labconfig could be a convenient way to auto-load different application configurations and different connection tables for the same apparatus, but:

• Application configurations can be changed manually using the File » Load configuration menu. Is there a reason not to, other than convenience?
• This is a misuse of the keyword for modifying the connection table of an apparatus, as you say:

The connection table is pretty much a one-to-one mapping to an apparatus

For the use case you mention, why did the different experimental projects not use a subset of a common, authoritative connection table for the apparatus, other than convenience?

[chrisjbillington]

Is there a reason not to, other than convenience?

Not much - switching the experiment name would just switch them all at once (but that's not saving much since there aren't many apps.). It would also add an extra layer of hierarchy to the shot files to separate the data from different projects, which is kind of nice but I don't think not having this would be ruining anyone's day.

For the use case you mention, why did the different experimental projects not use a subset of a common, authoritative connection table for the apparatus, other than convenience?

We never actually used the switching of experiment_name for this, so no, we just used a single connection table. I was just proposing switching experiment_name as an alternative to what we were doing, but following that thought to the implication of having to move the connection table into a shared location made it less appealing.

At NIST/UMD we have not followed the model of having a lab connection table which experiments duplicate the relevant subset of - we have experiment scripts import the 'master' connection table as their own. The separation of lab connection table from what experiment scripts are using is a neat separation in principal but few people see the duplication as worth it and I think I agree with them.

So if we were switching experiment_name to switch projects, we would probably have just renamed our connection table to rb_chip_connectiontable and set its .py file and .h5 filepaths in labconfig directly to %(shared_drive)s\Experiments and %(userlib)s\labscriptlib\ without the experiment_name.

This is workable though. I could imagine doing it - but all it's getting you is auto-loading a few config files and a slightly different folder hierarchy.

[rpanderson]

At NIST/UMD we have not followed the model of having a lab connection table which experiments duplicate the relevant subset of - we have experiment scripts import the 'master' connection table as their own.

This practice is good and we should demonstrate it in the example experiment scripts/documentation.

The separation of lab connection table from what experiment scripts are using is a neat separation in principal but few people see the duplication as worth it and I think I agree with them.

It can be useful in cases where instantiating all devices in the connection table of an apparatus is burdensome to do in a given experiment script, e.g. when testing a very small subset of devices, and instantiating everything else would require a relatively larger minimum set of instructions.

Should we implement this in v3.0 and/or issue a DeprectationWarning for (but continue to permit) the use of experiment_name?

[philipstarkey]

While this is somewhat off topic, I don't agree that importing your connection table from another file is good practice (although it is convenient). It ultimately moves connection table compatibility errors to the compilation stage (you get a Python error during compilation from including the current and incompatible connection table - usually due to an undefined variable) rather than the shot submission stage (where BLACS sends you a connection table diff. This behaviour also prevents you from compiling old scripts and viewing the results in runviewer.

It also makes it more complex to use globals to change things like acquisition rate or include/exclude certain devices (for example, specific cameras depending on imaging mode).

I'm not saying it's always bad to do, it's certainly convenient, but there are also some good reasons not to do it.

[rpanderson]

Great points, @philipstarkey. This practice shouldn't be the default but instead comprise a tutorial with the caveats you identify.