internship.txt

Misc
====

Mail:

To access your email account go to the following site:
https://webmail.lrde.epita.fr

If you notice a serious bug that needs fixing you can send an e-mail at:
vcsn-dev@lrde.epita.fr

SSH:
To connect to the laboratory with ssh you simply need to type:
    $ ssh login@lrde.epita.fr -Y
    $ ssh node7 -Y
The -Y option enables the graphical mode.

Vcsn installation:
    $ ssh-keygen
This will create an ssh key.

Send your id_rsa.pub to admin@lrde.epita.fr. He will then add your key to the
vcsn git repository. Once added you can:

$ ssh node7
    $ source /lrde/dev/profile
    $ git clone git@gitlab.lrde.epita.fr:vcsn/vcsn.git
    $ cd vcsn
    $ ./configure CXX=g++4.9
    $ make install
    $ make check

"make check" will do several tests. They should all pass, except one
that is an expected failure. Create a special directory where you will
have all your binary files:

    $ mkdir _build
    $ g++ --version
    $ mkdir _build/49d

49 is the g++ version, d stands for "debug".

    $ cd _build/49d
    $ ../../configure

A "speed" configuration is:

    $ mkdir _build/49s
    $ cd _build/49s
    $ ../../configure CPPFLAGS='-DNDEBUG' CXXFLAGS='-O3 -g3'

Bashrc:
Here is an example for your bash configuration.
Create the file ~/.bashrc and copy this in it:
---------------------------------------------
alias ls='ls --color'
export EDITOR=vim        # Enables your default editor.
source /lrde/dev/profile #Activates efstcomile and other stuff.
49s()
{
  make -C _build/49s "$@"
}
# 49s() is a function declaration. When you type 49s on the shell it will run
# that function. The "$@" option means add any option you type on the shell.
d()
{
  dot -Tpdf "$@" > /tmp/automaton.gv
  evince /tmp/automaton.gv
}
# now to display an automaton all you need to do is type :
# d share/vcsn/lal_char_b/a1.gv
---------------------------------------------
If you are using zsh, the following function works better for reading dot files.
d()
{
  eog =(dot -Tpng "$@")
}
--------------------------------------------
Source your bashrc file by typing the following command:
    $ source ~/.bashrc
Now you can run the following command:
    $ 49s check -j20
This will compile and put all the generated files in _build/49s

What is an automaton:
An automaton can be seen as a function that takes words, letters or nullable
letters as an entry and returns you the cost of that expression. An automaton
is composed of different states. The initial and final states can have a
weight. Every states can be linked by a transition that contains a weight
and a label.

Vcsn:
Contexts:
A context is what gives you a precise definition of an automaton. It gives
you:
    - the alphabet you are working with,
    - the type of labels.
    - the type of weights.
Here is an example:
lan_char(abc), b: The labels are nullable (either epsilon or a letter). The
alphabet is "abc" and the weights are booleans.
Labels can also be words (law), or letters (lal).
Weights can be:
    - Real (_r)
    - Rational expressions (_expressionset<lal_char(ab), b)
    - z_min (Shortest path).
    - And many others.
If we take lal_char(ab), z, another way for intepreting that context is:
{a,b}->Z which is a function that takes a's and b's as input and returns
an integer.
And law_char(ab), expressionset<lal_char(x,y), z> can be intepreted as:
{a,b}*->{x,y}->Z which is an automaton that take words composed of a's and b's
and that returns a rational expression that takes x's and y's as input and
returns integers.

Create an automata:
The "standard" algorithm allows you to create an automaton from a rational
expression. Lets create an automaton that accepts the word "a" and whose
context is "lal_char(a), b". Type the following command to create that
automaton:
    $ vcsn standard -E -e '(?@lal_char(a), b)(a)'
If you wish to display this automaton you can type:
    $ vcsn standard -E -e '(?@lal_char(a), b)(a)' | d
PS: This will only work if you are using the bashrc file given earlier.

Cost of a path:
A path is valid if you start on an initial state and "eat" all the letters of
the input and land on a final state. The cost of that path is the product of
the cost of each transitions from the initial to the final state. The result is
then multiplied by the weight of the initial state (a left multiplication) and
then multiplied by the weight of the final state (a right multiplication).

Weightset definition:
Z=<Z,+,x>
The weights are integers.
We use the "x" operation to multiply the cost of each transition in a path.
We use the "+" operation to add the cost of all the possible paths together.

Zmin=<Z,rmin,+>
The weights are integers.
The "+" operation means that the cost of each transition is added up together.
The "rmin" operation means that the path with the lowest cost is returned.
In the end Zmin acts the same as finding "the shortest path".

pre=<KRat,+,.>
The weights are rational expressions.
The weight of every transition of a valid path is concatenated by ".". Then,
all the paths are added together  by "+". This can give the following results :
    - (a.b)+(x.y)
    - (<2>a.<2>b) + (<31>x.<42y>)

Dot syntax:
The file extension given to these files is ".gv". You can find several samples
in "share/vcsn/".
"vcsn_context" allows us to immediately know the definition of the automaton.
Then the letters "I" and "F" followed by any number represent the pre and
post states. These are invisible states and have a transition to an
initial or a final state. That transition can only be labeled by a weight.
Finally, we write the different transitions with the following syntax:
    - "state1 -> state2 [label = "a, b"]"
    - "0 -> 1 [label = "<42>abc"]
    - "0 -> F0"

Using an automaton:
The file "vcsn/core/mutable-automaton.hh" contains all the functions you will
need to manipulate an automaton. Here are a few examples:
aut = an automata object.
aut.all_transitions()                # includes pre and post transitions.
aut.transitions()                    # just normal transition.
aut.label_of(t)                      # gets the labels of a transitions.
aut.states()                         # gets all the states.
aut.set_initial(s)                   # make s an initial state.
aut.add_transition(src, dst, l, w)   # src -> dst [label = "<w>l"]

Static and Dynamic API:
Different namespaces have been created to differentiate the APIs.
"vcsn::dyn" is all the dynamic code (Notice you won't see any templates for
the context and automaton type).
The "vcsn" namespace is the static code.
"vcsn::ctx" is the namespace with all the different contexts.
"vcsn::detail" is extra code that does not need to be known by the user.

Tools:
Tools contains all the binaries of Vcsn. There is a different "program"
for each existing algorithm in Vcsn. They all start by "vcsn-"
You find these files in "bin/". The tests for the different "programs" are in
"tests/tools/"

Git:
Once Vcsn is running and working you should create a new branch.
    $ git checkout -b "my_branch_name" :
This branch will be your working branch and only seen by you. To create a
branch on the remote machine, you need to type:
    $ git push origin HEAD:al/my_branch_name
"origin" is the name of the machine you are creating a new branch on. "HEAD"
means you wish to push all the work on your current local branch. "al" is your
initials.
Here are a few useful commands.

    $ git branch -a                        : Shows you all the branches.
    $ git add -u                           : Add every files for next commit.
    $ git add "file_name"                  : To add new files.
    $ git commit -a                        : To commit all the files.
    $ git commit --amend                   : Allows to change last commit.
    $ git log                              : Shows you the commit history.
    $ git log -p --reverse origin/master.. : Shows you the commit history in revers order, and shows all the modifications made.
    $ git show                             : Shows you last commit in detail.
    $ git status                           : Gives information on the status of each file, and the branch you are currently working on.
    $ git fetch                            : updates your origin/master to the current location of master in Vcsn.
    $ git rebase origin/master             : puts your branch up to date by having its base start at the new location of "origin/master".

Note: Never use "git pull". This make messy merges and a non-linear history.

Once you have done all your commits you can reorder them and rewrite the commit
message by:
    $ git rebase origin/master -i
Now you can push your work so that others can see what you did.
    $ git push origin HEAD:al/my_branch
If you forget "HEAD" it means you will push nothing on the branch al/my_branch
and therefore will result in deleting that branch.
Note: if you rebased your branch to be up to date with origin/master you
will need to add the option "-f" to force your push:
    $ git push origin -f HEAD:al/my_branch
The reason is that after rebasing, your curent branch and the branch on the
server no longer have the same base (i-e different history log).

Git config:
Create file ~/.gitconfig and add:
-----------------------------------------
[alias]
  st = status
  amend = !EDITOR=: git commit --amend
[user]
  name = Alexandre Lewkowicz
  email = alexandre.lewkowicz@epita.fr
[core]
  excludesfile=/lrde/home/stage/alewkowicz/.gitignore
[color]
  ui = true
-----------------------------------------

Create file ~/.gitignore and add:
-----------------------------------------
_build
----------------------------------------

Debugging:
The following command allows you to debug your program.
libtool exe gdb --args bin/vcsn-cat -f share/vcsn/lal_char_b/a1.gv


.. Local Variables:
.. mode: rst
.. End: