Skip to content

add initial usage and getting started sections #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MattZur merged 3 commits into from
Apr 2, 2025
Merged

add initial usage and getting started sections #33

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
56066b3
add initial usage and getting started sections
MattZur Apr 1, 2025
ddd52e4
changes to usage, getting started, and what is mule sections; add mul…
MattZur Apr 2, 2025
d149a2f
fixed typos and made Usage section more general
MattZur Apr 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,37 @@ The functionality of this repository should cover:

## Usage

Implement description of full usage, perhaps move this section to docs.
Usage is currently focused on binary files for readout from the above named systems.
Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since it hasn't been referenced anywhere, I would specify that the software used for data acqusition is WaveDump 1 and 2. Possibly I'd even change the 'What is MULE section' first bulletpoint to highlight that, instead of doing it here.

Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph brings up a good point, currently the only usage is data processing, perhaps there should be a 'roadmap' of basic features desired in MULE that we can work towards.

If you want, you can open your first issue addressing this :)


After data collection and having saved the .bin files into the desired directory, one should copy the file path into the config file using a text editor (such as vim). In addtion, the destination file path and name should be enetered in the save_path line. Finally, ensure to have the correct wavedump edition as that will affect decoding.
Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo enetered -> entered.

We don't just have .bin files at the moment, we also have .dat (for WD1 processing). I'd keep the filetype vague, instead just 'the input file' or something along those lines. This means if we add further filetypes in later the sentence will still apply.

Copy link
Member

@jwaiton jwaiton Apr 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MULE is made to be run anywhere on your system by design, once you've run the setup.sh you don't need to move the data into the config files, you can process them wherever they end up, as long as the paths in the config are correct.

Likewise, the configs can be copied and pasted wherever you so wish, the ones provided are so the user knows what inputs are required to make the configs work.


> **_NOTE_** One can find the config file in /MULE/packs/configs

Once the config file has been edited and saved, one can execute the program from the terminal, after navigating to the directory where the config file was saved, by running:

`mule proc process_WD2_3channel.conf`

This will generate the .h5 file and store them in the predefined location.

In addition, there are several processing funcitons which are not yet run automatically from the config file but that can be found in /MULE/packs/proc
Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is another good point! I'd possibly add subheaders (in markdown you increase the hashtags) for 'running MULE' and 'auxilary tools' or something along those lines.

In the future we should add a link to the automated documentation of these functions found here at the moment.


## Getting Started

EXPLAIN SIMPLEST METHOD FOR INSTALLATION/SETUP
The simplest method of installation is one done by cloning the github repository and running the setup.sh file from the terminal, as explained below.

To clone the directory one should install git from the terminal with something like pip:

`pip install git`
Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pip is a package manager specifically supplied for python. Installing git on different machines differs quite a bit. For the sake of sanity, lets remove this and hope the user knows how to install packages on their machine :)


then, one can clone the repo to the desired directory by using,

`git clone https://github.com/nu-ZOO/MULE.git`

> **_NOTE_** The above link is taken from the repo's github page

The environemnt then needs to be created and activated. This can be achieved by running the following command from the MULE directory:

`source setup.sh`

One can also create an alias to activate the environment easily on every session.
Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first paragraph is perfect, but I would suggest to provide all the commands a user would have to type in a code block, like so:

git clone https://github.com/nu-ZOO/MULE.git
cd MULE
source setup.sh

Don't worry about informing the user about what each step does, the 'basic installation' should just be answering the question: 'I don't care what it means, I just want MULE to start running'.

The comment on the alias is also good :)

Copy link
Member

@jwaiton jwaiton Apr 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although, possibly warn them about two things:

  • Currently setup.sh only works as expected on x86_64 machines. This will be fixed soon.
  • This will try to install miniconda on your machine.