Python Accelerator Middle Layer
Content for tutorials #57
Replies: 3 comments 8 replies
|
What do you think @gubaidulinvadim, @simoneliuzzo, @kparasch, @GamelinAl, @marlibgin2, @HZBries? |
|
I agree with you, I would maybe even go further and say that we need lesson plans (or tutorial plans). I am not sure I understood correctly if your list is a single tutorial or several tutorials. For me the difference between a how-to and a tutorial is quite straightforward:
I would say that we need a tutorial for pyAML configuration but most of the others should fully skip this step, so either start from an existing configuration or use interactive mode w/o configuration. Regarding control system, if the user need to set-up the virtual accelerator as a 1st step I think we may loose many users before they even start. So I would keep this for later stages and start simple in pure python with the simulator mode. Possible tutorial topics:
For me these three tutorials are already a very good point to start a new user. That's what I would like to have, after this you can more or less handle yourself with the how-to section. |
|
Yes, probably both download and collab (there are other options than Google too; Google Colab is just what is used for mbtrack2 and Uni Paris-Saclay tutorials). I don't know about resource restrictions but this should not be an issue for us. |
|
I'm not entirely sure that the tutorials should be independent. I think they should be made according to a progression in complexity so you can follow them as a lecture series. But they can probably be done in such a way that you can jump in at any point and that tutorial is self-contained where everything needed from the earlier tutorials is already set up. If we do it like that we can probably fit both the option to start from manually creating a device and the option to start from loading a configuration in the same tutorial chain because at some point in the suggestion list I had you are going to have a quite full configuration to load. |
I will investigate this. There is also Github codespaces where people can have vs code in the browser and run notebooks in that interface. Or also binder. |
|
This also looks like an interesting option: https://jupyterbook.org/ |
|
Mm, look at this. I think that's what we want. You can download it but also launch it and run directly. And it's nicely separated from the content in the right sidepanel. https://scikit-learn.org/stable/auto_examples/classification/plot_classifier_comparison.html |
|
Do you think there is a need for a tutorial where we have a full configuration with all possible devices? In the suggestion I had my idea was to limit it only to quadrupoles, tune and potentially chromaticity to show the combined function magnet. So for example no BPMs. I think it would be useful for people to see configuration files from other machines when figuring out how to set up their configuration, but maybe that is better as a library of configuration files that you can browse rather than something that you can run directly in a tutorial? Could even be that it shouldn't be a library of full files but just configuration examples for specific devices/applications? Then people could go there and if they for example know that they have a magnet similar to SOLEIL II or orbit object similar to BESSY II they can find it there and copy it as a template. I guess potentially in the future you could even copy templates like that, modify and merge them together into the configuration for your machine with the configuration manager. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
The new page for documentation is set up: https://python-accelerator-middle-layer.github.io/documentation/. See #53 for background about the new structure.
One thing left to do is to add tutorials. The difference between a tutorial and a how-to guide isn't entirely easy to understand but I have thought about it in the context of our users and I think we could make the following distinction:
How-to guide: this is for the already committed user. Someone who has decided that they want to use pyAML and are looking for information about how to do a specific task. It can be both new and experience users but they have some goal in mind.
Tutorial: this is for users who haven't decided yet if they want to use pyAML. They are curious, want to try out and see if the code is for them.
After studying the details of Diátaxis I concluded that a tutorial should be a lesson which led me think that we should arrange our tutorials as a set of lessons which follows a lesson plan. The goal of this plan should be to guide the user from knowing nothing, through the most important features and in the end leave them in a state where they are a committed user who has an idea how to start and what to do next to set it up for their own machine. At that point they should move on to the how-to guides.
Observational studies
To better understand how to write good tutorials I have done some observational studies in the BESSY II and MLS control rooms to understand what it is people want to do when they try a new code. We currently have a wide range of users from bachelor students to senior scientists learning various tools (MML, ophyd-async, bluesky, pyepics, p4p etc) for doing their measurements so I think it's a good representation of the pyAML users. My conclusion was this:
-> They want to do something immediately. It can be something very easy and trivial but it has to be motivating. If I tell them that they first need to set up a configuration they are gone. Instead of "Yeah! I can read from the control system with this new tool" it becomes "Uhh... I don't want to do. I just keep using the tools I already use because it will give me the result faster".
Lesson plan suggestion
Based on that I have come up with a suggestion for a lesson plan for the tutorials. I know that all features in it aren't implemented yet but I thought if we have a plan for what we want the tutorials to contain it also becomes easier to know what to implement next.
Context:
The tutorials should all use the same example accelerator. This can be the simple accelerator we now have for the integration tests. There needs to be some basic information about the parameters of that lattice, optics etc.
The users are going to want to use a specific control system for the tutorial. Someone from a TANGO lab isn't going to get attracted by doing a tutorial using EPICS and vice versa. So we need at least two paths in the tutorials for TANGO and EPICS despite that for the later parts things will be control system agnostic.
Tutorials:
Create a single device directly in Python. This is to immediately go for the goal that the users are interested in: how to read and set in the real machine. For the tutorial this will however be done on a virtual accelerator.
Create a second device to read the effect of the first device.
Now put together an accelerator configuration with only these two devices. At this point I think the users have become sufficiently motivated to understand the point of the yaml file.
Add simulator mode to the configuration
Add unit conversions
Make quadrupoles serialized
Add a second quadrupole family
Configure delays/sleeps/tolerances for devices
Configure and run the tune correction tool using the two quadrupole families
Turn the quadrupoles into combined function quadrupole-sextupole magnets
etc... The point is to increase the complexity as the tutorials go along and give the user a tour of the most important functionality.
What do you think?
All reactions