Planets - User contributions [en]

Some Ferret tips and pointers

2026-04-29T08:40:25Z

Mwolff: /* Commands used on a Macbook Pro with the M3 ARM chipset (April 2026) */

== Ferret ==
Ferret is a NetCDF vizualisation tool which can be used to postprocess and visualize PCM outputs.

This free software is from NOAA (National Oceanic and Atmospheric Administration) and the relevant webpage where you can learn how to install and use it is here: https://ferret.pmel.noaa.gov/Ferret/

[For Mac users] It is recommended to use/migrate-to PyFerret. However, there is a bug in later versions that can render plotting problematic even in the Linux environment. Fortunately, there is a work around, which we will address specifically for the Mac environment (a post to the Ferret listserv is referenced, and it deals specifically with Linux). See [[Some_Ferret_tips_and_pointers#Installation_tips| section below]].

== For first timers ==
Ferret is essentially a command line tool so the first thing you'll need to do is launch it from your terminal
<syntaxhighlight lang="bash">
ferret
</syntaxhighlight>
(on some system, e.g. Ubuntu, the executable is called '''ferret_c''' (and the related package '''ferret_viz''') because another unrelated software also called '''ferret''' exists).

Once under Ferret you should see the Ferret prompt:
<pre>
yes?
</pre>

To load a datafile, for example '''diagfi.nc''' issue command:
<pre>
yes? use diagfi.nc
</pre>
Once the file has been loaded, you can query for its contents with the command '''show data'''. This will let you know about available fields (and their shapes: usually i along longitudes, j along latitudes, k along pseudo-altitudes and l along time). e.g
<pre>
yes? show data
currently SET data sets:
1> ./diagfi.nc (default)
name title I J K L
AIRE 1:65 1:49 ... ...
PHISINIT 1:65 1:49 ... ...
TSURF 1:65 1:49 ... 1:1464
PS 1:65 1:49 ... 1:1464
TEMP 1:65 1:49 1:73 1:1464
U 1:65 1:49 1:73 1:1464
V 1:65 1:49 1:73 1:1464
</pre>
In the example above the file contains '''AIRE''' and '''PHISINIT''', which are 2D (indexed along i and j indexes, i.e. longitude and latitude == surface fields), '''TSURF''', '''PS''', which are 3D (indexed along i, j and l indexes, i.e. longitude, latitude and time == surface fields evolving in time) and '''TEMP''', '''U''' and '''V''', which are 4D).

== Various tips and pointers ==
* Don't kill the Ferret graphic plot window (by clicking on the cross at the top right corner); Ferret won't recover, you'll have to exit and start again...
* One can refer to a field coordinates either via indexes '''i''', '''j''', '''k''', '''l''' or via associated real world coordinates '''x''', '''y''', '''z''', '''t'''.

==== How to make a 1D plot ====
You simply need to specify along which coordinate the variable is fixed and not mention the one along which it should be plotted, e.g.
<pre>
yes? plot/i=13/j=15 PS
</pre>
Or equivalently
<pre>
yes? plot PS[i=13,j=15]
</pre>
Or similarly using real world coordinates, e.g.
<pre>
yes? plot PS[x=12,y=35]
</pre>
Note that when using real world coordinate, if the sought coordinates are not exactly those of the underlying grid then Ferret will use the nearest neighbor (and not interpolate to the desired coordinates).

One may limit the range of the coordinate along which the plot is made by explicitly providing the interval boundaries, e.g. to plot PS value at grid indexes i=13 and j=15 but for l ranging from 240 to 480:
<pre>
yes? plot PS[i=13,j=15,l=240:480]
</pre>

==== How to make a 2D map ====
Same story as for a 1D plot, one needs to specify along which the coordinates the variable is fixed and not mention the remaining two along which the map should be made. e.g.
<pre>
yes? shade TSURF[l=120]
</pre>
Note that with "shade" the output maps is raw (cell values are displayed as homogeneous tiles); if you want Ferret to smooth between grid points then use "fill":
<pre>
yes? fill TSURF[l=120]
</pre>

==== How to list data values ====
Just use "list" instead of "plot" or "shade" etc. to get the values of the field

==== How to compute an average ====
There are some operators which can be applied along axes, namely "@ave" for averaging (there are also "@min" for extracting minimum value, "@max" for extracting the maximum value and ""@sum" for computing the sum) which can be used on variables.
For example to display the map of the time average over the whole time series of TSURF:
<pre>
yes? shade TSURF[l=@ave]
</pre>
Or to display the latitude-altitude map of the zonal value of TEMP at time index 12:
<pre>
yes? shade TEMP[x=@ave,l=12]
</pre>
Operators can be combined and applied along different direction; for instance to display the time averaged zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
</pre>
The operators can also be applied to a sub-set of the axis; for instance to display the temporal average evaluated between time steps 48 and 96 of the zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=48:96@ave]
</pre>

==== Saving the figure ====
After the plot command use the "FRAME" command (and specify output file name, which has to be .gif), e.g.:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
yes? FRAME/FILE="mygreatplot.gif"
</pre>

==== Creating intermediate variables ====
You can create your own intermediate variable combining existing ones using the command "let", e.g. with
<pre>
yes? let MASS_MTOT=MTOT*AIRE
</pre>
where "MTOT" is the column amount of water vapor (in kg/m2) and "AIRE" is the mesh area (in m2) we create a new field "MASS_MTOT" which is the mass of water vapor (in kg) in each column.

You can then use your variable just like any other, including applying operations on it. For instance you can sum over longitudes and latitudes "MASS_MTOT" to plot the time evolution of the total planetary amount of water vapor (in kg) with:
<pre>
yes? plot MASS_MTOT[i=1:64@sum,j=@sum]
</pre>
where by the way we sum only over the first 64 longitude points as the 65th (longitude +180°) is redundant with the 1st (longitude -180°).

==== Writing instructions as jnl scripts ====
You can write up some (ASCII) text file containing a series of Ferret commands, and save it as a "journal" script with the extension ".jnl", e.g. "myscript.jnl". To load it in your Ferret session simply use the command "go":
<pre>
yes? go myscript
</pre>

== Installation tips ==

=== Ubuntu ferret_c environment ===
On the Ubuntu Linux where Ferret comes as "ferret_c", if the executable crashes when attempting to pot with a message of the likes of
<pre>
PPL+ error: Unable to read "default.spk" to set shade and fill colors.

*** NOTE: Fonts directory is undefined. Check the Ferret environment.
**ERROR: file undefined or not found: fondat.dat
</pre>
This is most likely because it is missing some necessary environment variable. The cure is easy: you should
<syntaxhighlight lang="bash">
source /usr/share/ferret-vis/bin/ferret_paths
</syntaxhighlight>
before running ferret_c (and possibly add that command in your .bashrc to not have to issue it every time you want to run Ferret).

===Mac OSX (PyFerret) and Graphics bug===

====Miniconda====
conda is the preferred environment for the install. miniconda (a subset of conda) is a lighter-weight option which is a good choice. Installation instructions for both may be found [https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html here].

====PyFerret====
Once one has a conda installation of some type, the instructions are straight-forward. The official installation documentation is [https://github.com/NOAA-PMEL/PyFerret/blob/master/README.md here].

====Commands used on a Macbook Pro with the M3 ARM chipset (April 2026)====

* Install miniconda using script

<pre>
bash Miniconda3-latest-MacOSX-arm64.sh #can "yes" to activate, but we will deactivate

# do not automatically activate on startup
conda config --set auto_activate_base false

# initialize for tcsh (it will write code into one's .tcshrc file)
/Users/mwolff/miniconda3/bin/conda init tcsh
</pre>

* Install pyferret (latest version)
It is recommended that one use virtual environments, and alias the environment activation for simplicity. The following section is to install pyferret in virtual environment called FERRET.

Note: the pyferret command from the official site did NOT work for me. It complained about not finding the needed packages. For reference, this command was
<pre>
# line below did not work. it is here for reference
conda create -n FERRET -c conda-forge pyferret ferret_datasets --yes
</pre>

In addition, the numpy version in the Anaconda distribution has changed (since I last did this in 2024), as has the syntax to find the relevant package channel. So you need to restrict to it be less than version 2 and to specify the architecture with environment variable. Use the following instead [syntax is for zsh or bash]:
<pre>
CONDA_SUBDIR=osx-64 conda create -n FERRET -c conda-forge pyferret ferret_datasets "numpy<2" --yes
</pre>

This can be activated using an alias for brevity.
<pre>
alias FERRET "conda activate FERRET" #(t)csh
alias FERRET="conda activate FERRET" # zsh or bash
</pre>

* Dealing with plotting bug. As can be seen in the post on the Ferret group [https://www.pmel.noaa.gov/maillists/tmap/ferret_users/fu_2019/msg01059.html here], there can be problems for plotting with the latest version(s), even on Linux. Below, we use a set of commands that works for Mac OSX.

Install a slightly older version of pyferret (i.e., one where the plotting works) using the command in the referenced post in the last paragrph):
<pre>
# We have had to change the channel from the example in the referenced ferret group post as described, and the zsh/bash command is:

CONDA_SUBDIR=osx-64 conda create -n oldFERRET -c conda-forge/label/cf202003 pyferret ferret_datasets "numpy<2" --yes

</pre>

Assuming an alias oldFERRET that activates this older version, a plotting test can be runs as
<pre>
[mwolff@renaudin ~ % oldFERRET
(oldFERRET) mwolff@renaudin ~ % pyferret
NOAA/PMEL TMAP
PyFerret v7.5 (optimized)
Darwin 17.7.0 - 12/16/19
29-Apr-26 10:04

yes? use coads_climatology
yes? fill sst[l=1]

</pre>

[[File:Ferret_testplot_coads.png]]

[[Category:FAQ]]

Some Ferret tips and pointers

2026-04-29T08:37:30Z

Mwolff: /* Commands used on a Macbook Pro with the M3 ARM chipset (April 2026) */

== Ferret ==
Ferret is a NetCDF vizualisation tool which can be used to postprocess and visualize PCM outputs.

This free software is from NOAA (National Oceanic and Atmospheric Administration) and the relevant webpage where you can learn how to install and use it is here: https://ferret.pmel.noaa.gov/Ferret/

[For Mac users] It is recommended to use/migrate-to PyFerret. However, there is a bug in later versions that can render plotting problematic even in the Linux environment. Fortunately, there is a work around, which we will address specifically for the Mac environment (a post to the Ferret listserv is referenced, and it deals specifically with Linux). See [[Some_Ferret_tips_and_pointers#Installation_tips| section below]].

== For first timers ==
Ferret is essentially a command line tool so the first thing you'll need to do is launch it from your terminal
<syntaxhighlight lang="bash">
ferret
</syntaxhighlight>
(on some system, e.g. Ubuntu, the executable is called '''ferret_c''' (and the related package '''ferret_viz''') because another unrelated software also called '''ferret''' exists).

Once under Ferret you should see the Ferret prompt:
<pre>
yes?
</pre>

To load a datafile, for example '''diagfi.nc''' issue command:
<pre>
yes? use diagfi.nc
</pre>
Once the file has been loaded, you can query for its contents with the command '''show data'''. This will let you know about available fields (and their shapes: usually i along longitudes, j along latitudes, k along pseudo-altitudes and l along time). e.g
<pre>
yes? show data
currently SET data sets:
1> ./diagfi.nc (default)
name title I J K L
AIRE 1:65 1:49 ... ...
PHISINIT 1:65 1:49 ... ...
TSURF 1:65 1:49 ... 1:1464
PS 1:65 1:49 ... 1:1464
TEMP 1:65 1:49 1:73 1:1464
U 1:65 1:49 1:73 1:1464
V 1:65 1:49 1:73 1:1464
</pre>
In the example above the file contains '''AIRE''' and '''PHISINIT''', which are 2D (indexed along i and j indexes, i.e. longitude and latitude == surface fields), '''TSURF''', '''PS''', which are 3D (indexed along i, j and l indexes, i.e. longitude, latitude and time == surface fields evolving in time) and '''TEMP''', '''U''' and '''V''', which are 4D).

== Various tips and pointers ==
* Don't kill the Ferret graphic plot window (by clicking on the cross at the top right corner); Ferret won't recover, you'll have to exit and start again...
* One can refer to a field coordinates either via indexes '''i''', '''j''', '''k''', '''l''' or via associated real world coordinates '''x''', '''y''', '''z''', '''t'''.

==== How to make a 1D plot ====
You simply need to specify along which coordinate the variable is fixed and not mention the one along which it should be plotted, e.g.
<pre>
yes? plot/i=13/j=15 PS
</pre>
Or equivalently
<pre>
yes? plot PS[i=13,j=15]
</pre>
Or similarly using real world coordinates, e.g.
<pre>
yes? plot PS[x=12,y=35]
</pre>
Note that when using real world coordinate, if the sought coordinates are not exactly those of the underlying grid then Ferret will use the nearest neighbor (and not interpolate to the desired coordinates).

One may limit the range of the coordinate along which the plot is made by explicitly providing the interval boundaries, e.g. to plot PS value at grid indexes i=13 and j=15 but for l ranging from 240 to 480:
<pre>
yes? plot PS[i=13,j=15,l=240:480]
</pre>

==== How to make a 2D map ====
Same story as for a 1D plot, one needs to specify along which the coordinates the variable is fixed and not mention the remaining two along which the map should be made. e.g.
<pre>
yes? shade TSURF[l=120]
</pre>
Note that with "shade" the output maps is raw (cell values are displayed as homogeneous tiles); if you want Ferret to smooth between grid points then use "fill":
<pre>
yes? fill TSURF[l=120]
</pre>

==== How to list data values ====
Just use "list" instead of "plot" or "shade" etc. to get the values of the field

==== How to compute an average ====
There are some operators which can be applied along axes, namely "@ave" for averaging (there are also "@min" for extracting minimum value, "@max" for extracting the maximum value and ""@sum" for computing the sum) which can be used on variables.
For example to display the map of the time average over the whole time series of TSURF:
<pre>
yes? shade TSURF[l=@ave]
</pre>
Or to display the latitude-altitude map of the zonal value of TEMP at time index 12:
<pre>
yes? shade TEMP[x=@ave,l=12]
</pre>
Operators can be combined and applied along different direction; for instance to display the time averaged zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
</pre>
The operators can also be applied to a sub-set of the axis; for instance to display the temporal average evaluated between time steps 48 and 96 of the zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=48:96@ave]
</pre>

==== Saving the figure ====
After the plot command use the "FRAME" command (and specify output file name, which has to be .gif), e.g.:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
yes? FRAME/FILE="mygreatplot.gif"
</pre>

==== Creating intermediate variables ====
You can create your own intermediate variable combining existing ones using the command "let", e.g. with
<pre>
yes? let MASS_MTOT=MTOT*AIRE
</pre>
where "MTOT" is the column amount of water vapor (in kg/m2) and "AIRE" is the mesh area (in m2) we create a new field "MASS_MTOT" which is the mass of water vapor (in kg) in each column.

You can then use your variable just like any other, including applying operations on it. For instance you can sum over longitudes and latitudes "MASS_MTOT" to plot the time evolution of the total planetary amount of water vapor (in kg) with:
<pre>
yes? plot MASS_MTOT[i=1:64@sum,j=@sum]
</pre>
where by the way we sum only over the first 64 longitude points as the 65th (longitude +180°) is redundant with the 1st (longitude -180°).

==== Writing instructions as jnl scripts ====
You can write up some (ASCII) text file containing a series of Ferret commands, and save it as a "journal" script with the extension ".jnl", e.g. "myscript.jnl". To load it in your Ferret session simply use the command "go":
<pre>
yes? go myscript
</pre>

== Installation tips ==

=== Ubuntu ferret_c environment ===
On the Ubuntu Linux where Ferret comes as "ferret_c", if the executable crashes when attempting to pot with a message of the likes of
<pre>
PPL+ error: Unable to read "default.spk" to set shade and fill colors.

*** NOTE: Fonts directory is undefined. Check the Ferret environment.
**ERROR: file undefined or not found: fondat.dat
</pre>
This is most likely because it is missing some necessary environment variable. The cure is easy: you should
<syntaxhighlight lang="bash">
source /usr/share/ferret-vis/bin/ferret_paths
</syntaxhighlight>
before running ferret_c (and possibly add that command in your .bashrc to not have to issue it every time you want to run Ferret).

===Mac OSX (PyFerret) and Graphics bug===

====Miniconda====
conda is the preferred environment for the install. miniconda (a subset of conda) is a lighter-weight option which is a good choice. Installation instructions for both may be found [https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html here].

====PyFerret====
Once one has a conda installation of some type, the instructions are straight-forward. The official installation documentation is [https://github.com/NOAA-PMEL/PyFerret/blob/master/README.md here].

====Commands used on a Macbook Pro with the M3 ARM chipset (April 2026)====

* Install miniconda using script

<pre>
bash Miniconda3-latest-MacOSX-arm64.sh #can "yes" to activate, but we will deactivate

# do not automatically activate on startup
conda config --set auto_activate_base false

# initialize for tcsh (it will write code into one's .tcshrc file)
/Users/mwolff/miniconda3/bin/conda init tcsh
</pre>

* Install pyferret (latest version)
It is recommended that one use virtual environments, and alias the environment activation for simplicity. The following section is to install pyferret in virtual environment called FERRET.

Note: the pyferret command from the official site did NOT work for me. It complained about not finding the needed packages. For reference, this command was
<pre>
# line below did not work. it is here for reference
conda create -n FERRET -c conda-forge pyferret ferret_datasets --yes
</pre>

In addition, the numpy version in the Anaconda distribution has changed (since I last did this in 2024), as has the syntax to find the relevant package channel. So you need to restrict to it be less than version 2 and to specify the architecture with environment variable. Use the following instead [syntax is for zsh or bash]:
<pre>
CONDA_SUBDIR=osx-64 conda create -n FERRET -c conda-forge pyferret ferret_datasets "numpy<2" --yes
</pre>

This can be activated using an alias for brevity.
<pre>
alias FERRET "conda activate FERRET" #(t)csh
alias FERRET="conda activate FERRET" # zsh or bash
</pre>

* Dealing with plotting bug. As can be seen in the post on the Ferret group [https://www.pmel.noaa.gov/maillists/tmap/ferret_users/fu_2019/msg01059.html here], there can be problems for plotting with the latest version(s), even on Linux. Below, we use a set of commands that works for Mac OSX.

Install a slightly older version of pyferret (i.e., one where the plotting works) using the command in the referenced post in the last paragrph):
<pre>
# we have had to change the channel from the example in the referenced ferret group post (to install for Mac OS). Implementing the recent changes described above, the zsh/bash command is:
CONDA_SUBDIR=osx-64 conda create -n oldFERRET -c conda-forge/label/cf202003 pyferret ferret_datasets "numpy<2" --yes
</pre>

Assuming an alias oldFERRET that activates this older version, a plotting test can be runs as
<pre>
[mwolff@renaudin ~ % oldFERRET
(oldFERRET) mwolff@renaudin ~ % pyferret
NOAA/PMEL TMAP
PyFerret v7.5 (optimized)
Darwin 17.7.0 - 12/16/19
29-Apr-26 10:04

yes? use coads_climatology
yes? fill sst[l=1]

</pre>

[[File:Ferret_testplot_coads.png]]

[[Category:FAQ]]

Some Ferret tips and pointers

2026-04-29T08:20:02Z

Mwolff: /* Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023) */

== Ferret ==
Ferret is a NetCDF vizualisation tool which can be used to postprocess and visualize PCM outputs.

This free software is from NOAA (National Oceanic and Atmospheric Administration) and the relevant webpage where you can learn how to install and use it is here: https://ferret.pmel.noaa.gov/Ferret/

[For Mac users] It is recommended to use/migrate-to PyFerret. However, there is a bug in later versions that can render plotting problematic even in the Linux environment. Fortunately, there is a work around, which we will address specifically for the Mac environment (a post to the Ferret listserv is referenced, and it deals specifically with Linux). See [[Some_Ferret_tips_and_pointers#Installation_tips| section below]].

== For first timers ==
Ferret is essentially a command line tool so the first thing you'll need to do is launch it from your terminal
<syntaxhighlight lang="bash">
ferret
</syntaxhighlight>
(on some system, e.g. Ubuntu, the executable is called '''ferret_c''' (and the related package '''ferret_viz''') because another unrelated software also called '''ferret''' exists).

Once under Ferret you should see the Ferret prompt:
<pre>
yes?
</pre>

To load a datafile, for example '''diagfi.nc''' issue command:
<pre>
yes? use diagfi.nc
</pre>
Once the file has been loaded, you can query for its contents with the command '''show data'''. This will let you know about available fields (and their shapes: usually i along longitudes, j along latitudes, k along pseudo-altitudes and l along time). e.g
<pre>
yes? show data
currently SET data sets:
1> ./diagfi.nc (default)
name title I J K L
AIRE 1:65 1:49 ... ...
PHISINIT 1:65 1:49 ... ...
TSURF 1:65 1:49 ... 1:1464
PS 1:65 1:49 ... 1:1464
TEMP 1:65 1:49 1:73 1:1464
U 1:65 1:49 1:73 1:1464
V 1:65 1:49 1:73 1:1464
</pre>
In the example above the file contains '''AIRE''' and '''PHISINIT''', which are 2D (indexed along i and j indexes, i.e. longitude and latitude == surface fields), '''TSURF''', '''PS''', which are 3D (indexed along i, j and l indexes, i.e. longitude, latitude and time == surface fields evolving in time) and '''TEMP''', '''U''' and '''V''', which are 4D).

== Various tips and pointers ==
* Don't kill the Ferret graphic plot window (by clicking on the cross at the top right corner); Ferret won't recover, you'll have to exit and start again...
* One can refer to a field coordinates either via indexes '''i''', '''j''', '''k''', '''l''' or via associated real world coordinates '''x''', '''y''', '''z''', '''t'''.

==== How to make a 1D plot ====
You simply need to specify along which coordinate the variable is fixed and not mention the one along which it should be plotted, e.g.
<pre>
yes? plot/i=13/j=15 PS
</pre>
Or equivalently
<pre>
yes? plot PS[i=13,j=15]
</pre>
Or similarly using real world coordinates, e.g.
<pre>
yes? plot PS[x=12,y=35]
</pre>
Note that when using real world coordinate, if the sought coordinates are not exactly those of the underlying grid then Ferret will use the nearest neighbor (and not interpolate to the desired coordinates).

One may limit the range of the coordinate along which the plot is made by explicitly providing the interval boundaries, e.g. to plot PS value at grid indexes i=13 and j=15 but for l ranging from 240 to 480:
<pre>
yes? plot PS[i=13,j=15,l=240:480]
</pre>

==== How to make a 2D map ====
Same story as for a 1D plot, one needs to specify along which the coordinates the variable is fixed and not mention the remaining two along which the map should be made. e.g.
<pre>
yes? shade TSURF[l=120]
</pre>
Note that with "shade" the output maps is raw (cell values are displayed as homogeneous tiles); if you want Ferret to smooth between grid points then use "fill":
<pre>
yes? fill TSURF[l=120]
</pre>

==== How to list data values ====
Just use "list" instead of "plot" or "shade" etc. to get the values of the field

==== How to compute an average ====
There are some operators which can be applied along axes, namely "@ave" for averaging (there are also "@min" for extracting minimum value, "@max" for extracting the maximum value and ""@sum" for computing the sum) which can be used on variables.
For example to display the map of the time average over the whole time series of TSURF:
<pre>
yes? shade TSURF[l=@ave]
</pre>
Or to display the latitude-altitude map of the zonal value of TEMP at time index 12:
<pre>
yes? shade TEMP[x=@ave,l=12]
</pre>
Operators can be combined and applied along different direction; for instance to display the time averaged zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
</pre>
The operators can also be applied to a sub-set of the axis; for instance to display the temporal average evaluated between time steps 48 and 96 of the zonal value of TEMP:
<pre>
yes? shade TEMP[x=@ave,l=48:96@ave]
</pre>

==== Saving the figure ====
After the plot command use the "FRAME" command (and specify output file name, which has to be .gif), e.g.:
<pre>
yes? shade TEMP[x=@ave,l=@ave]
yes? FRAME/FILE="mygreatplot.gif"
</pre>

==== Creating intermediate variables ====
You can create your own intermediate variable combining existing ones using the command "let", e.g. with
<pre>
yes? let MASS_MTOT=MTOT*AIRE
</pre>
where "MTOT" is the column amount of water vapor (in kg/m2) and "AIRE" is the mesh area (in m2) we create a new field "MASS_MTOT" which is the mass of water vapor (in kg) in each column.

You can then use your variable just like any other, including applying operations on it. For instance you can sum over longitudes and latitudes "MASS_MTOT" to plot the time evolution of the total planetary amount of water vapor (in kg) with:
<pre>
yes? plot MASS_MTOT[i=1:64@sum,j=@sum]
</pre>
where by the way we sum only over the first 64 longitude points as the 65th (longitude +180°) is redundant with the 1st (longitude -180°).

==== Writing instructions as jnl scripts ====
You can write up some (ASCII) text file containing a series of Ferret commands, and save it as a "journal" script with the extension ".jnl", e.g. "myscript.jnl". To load it in your Ferret session simply use the command "go":
<pre>
yes? go myscript
</pre>

== Installation tips ==

=== Ubuntu ferret_c environment ===
On the Ubuntu Linux where Ferret comes as "ferret_c", if the executable crashes when attempting to pot with a message of the likes of
<pre>
PPL+ error: Unable to read "default.spk" to set shade and fill colors.

*** NOTE: Fonts directory is undefined. Check the Ferret environment.
**ERROR: file undefined or not found: fondat.dat
</pre>
This is most likely because it is missing some necessary environment variable. The cure is easy: you should
<syntaxhighlight lang="bash">
source /usr/share/ferret-vis/bin/ferret_paths
</syntaxhighlight>
before running ferret_c (and possibly add that command in your .bashrc to not have to issue it every time you want to run Ferret).

===Mac OSX (PyFerret) and Graphics bug===

====Miniconda====
conda is the preferred environment for the install. miniconda (a subset of conda) is a lighter-weight option which is a good choice. Installation instructions for both may be found [https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html here].

====PyFerret====
Once one has a conda installation of some type, the instructions are straight-forward. The official installation documentation is [https://github.com/NOAA-PMEL/PyFerret/blob/master/README.md here].

====Commands used on a Macbook Pro with the M3 ARM chipset (April 2026)====

* Install miniconda using script

<pre>
bash Miniconda3-latest-MacOSX-arm64.sh #can "yes" to activate, but we will deactivate

# do not automatically activate on startup
conda config --set auto_activate_base false

# initialize for tcsh (it will write code into one's .tcshrc file)
/Users/mwolff/miniconda3/bin/conda init tcsh
</pre>

* Install pyferret (latest version)
It is recommended that one use virtual environments, and alias the environment activation for simplicity. The following section is to install pyferret in virtual environment called FERRET.

Note: the pyferret command from the official site did NOT work for me. It complained about not finding the needed packages. For reference, this command was
<pre>
# line below did not work. it is here for reference
conda create -n FERRET -c conda-forge pyferret ferret_datasets --yes
</pre>

In addition, the numpy version in the Anaconda distribution has changed, as has the syntax to find the relevant package channel. So you need to restrict to be less than version 2 and use an environment variable. So, use the following instead [syntax is for zsh or bash]:
<pre>
CONDA_SUBDIR=osx-64 conda create -n FERRET -c conda-forge pyferret ferret_datasets "numpy<2" --yes
</pre>

This can be activated using an alias for brevity.
<pre>
alias FERRET "conda activate FERRET" #(t)csh
alias FERRET="conda activate FERRET" # zsh or bash
</pre>

* Dealing with plotting bug. As can be seen in the post on the Ferret group [https://www.pmel.noaa.gov/maillists/tmap/ferret_users/fu_2019/msg01059.html here], there can be problems for plotting with the latest version(s), even on Linux. Below, we use a set of commands that works for Mac OSX.

Install a slightly older version of pyferret (i.e., one where the plotting works) using the command in the referenced post in the last paragrph):
<pre>
# we have had to change the channel from the example in the referenced ferret group post (to install for Mac OS). Implementing the recent changes described above, the zsh/bash command is:
CONDA_SUBDIR=osx-64 conda create -n oldFERRET -c conda-forge/label/cf202003 pyferret ferret_datasets "numpy<2" --yes
</pre>

Assuming an alias oldFERRET that activates this older version, a plotting test can be runs as
<pre>
[mwolff@renaudin ~ % oldFERRET
(oldFERRET) mwolff@renaudin ~ % pyferret
NOAA/PMEL TMAP
PyFerret v7.5 (optimized)
Darwin 17.7.0 - 12/16/19
29-Apr-26 10:04

yes? use coads_climatology
yes? fill sst[l=1]

</pre>

[[File:Ferret_testplot_coads.png]]

[[Category:FAQ]]

Using the MESOIPSL cluster

2025-02-26T13:54:21Z

Mwolff: /* Compiling the PCMs on Spirit */

This page provides some information for those who use the MESOIPSL clusters (also known as "spirit", replacing "ciclad").

Note that there are two distinct MESOIPSL Spirit clusters, one in Sorbonne Université (SU), and one in Ecole Polytechnique (X). If you log on to "spirit1" or "spirit2" (as shown below) then you are on the SU-Spirit cluster whereas if you log on to "spiritx1" or "spiritx2" then you are on the X-Spirit cluster.

If you need to run on GPUs, that is possible using the 3rd MESOIPSL cluster, HAL.

== How to access the cluster ==
If you had an account on Ciclad, then you have one on Spirit. If you need to open an account (this is of course reserved to IPSL users) then proceed to this page: https://documentations.ipsl.fr/spirit/getting_started/account.html

Once you have an account you can ssh to the cluster via either of the spirit1 or spirit2 login nodes:
<syntaxhighlight lang="bash">
ssh yourMESOIPSLlogin@spirit1.ipsl.fr
</syntaxhighlight>
or equivalently
<syntaxhighlight lang="bash">
ssh yourMESOIPSLlogin@spirit2.ipsl.fr
</syntaxhighlight>

IMPORTANT: the required ssh authentication level is such that it requires ED25519 or RSA (4096 bits) key types. If your ssh to the machines fails, the first thing to check is that you indeed are using RSA keys.

Here is probably also the right place to point to the MEOIPSL cluster's main page: https://documentations.ipsl.fr/spirit/

== OS and disk space ==
As the welcome message will remind you:
<pre>
Welcome to Ubuntu 20.04.5 LTS (GNU/Linux 5.4.0-125-generic x86_64)
CPU AMD EPYC 7402P 24-Core Processor 2.8GHz
=========================================================================
* Mesocentre ESPRI IPSL (Cluster Spirit) JUSSIEU *
=========================================================================
** Disk Space :
- /home/login (32Go and 300000 files max per user) : Backup every day.
- /data/login ( 1To and 300000 files max per user) : NO BACKUP
- /scratchu/login ( 2To and 300000 files max per user) : NO BACKUP
- /bdd/ : Datasets
- /climserv-home/, /homedata ,/scratchx : SpiritX workspace ( READ-ONLY)
------------------------------------------------------------------------------
Migration Documentation ( Temporary URL )
https://documentations.ipsl.fr/spirit/spirit_clusters/migration_from_ciclad_climserv.html
** Support Contact mailto:meso-support@ipsl.fr
------------------------------------------------------------------------------
</pre>
This is Ubuntu Linux and the "HOME" is quite limited in size. Most work should be done on the '''data''' and/or '''scratchu''' disks.

It is up to you to tailor your environment. By default it is quite bare; it is up to you to load the modules you'll need to have access to specific software or compilers or libraries (and versions thereof).
To know what modules are available:
<syntaxhighlight lang="bash">
module avail
</syntaxhighlight>
To load a given module, here the Panoply software:
<syntaxhighlight lang="bash">
module load panoply
</syntaxhighlight>

== Compiling the PCMs on Spirit ==
Dedicated arch files are available in the '''LMDZ.COMMON/arch''' subdirectory! They are labeled '''ifort_MESOIPSL''' (XIOS and DYNAMICO also have similarly named arch files).

Likewise there is a dedicated '''install_ioipsl_ifort_MESOIPSL.bash''' install script for IOIPSL available in '''LMDZ.COMMON/ioipsl'''

To compile the utilities, you should define the three varibles below as indicated, where the first line may have caused problems if you already tried it:
 NETCDF_HOME=$NETCDF_FORTRAN_ROOT
 COMPILER="ifort"
 COMPILER_OPTIONS="-O2 -ip"

== Example of a job to run a GCM simulation ==
Here to run using 24 MPI tasks with 2 OpenMP threads each:
<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=24
#SBATCH --cpus-per-task=2
#SBATCH --partition=zen4 # zen4: 64cores/node and 240GB of memory
##SBATCH --partition=zen16 # zen16: 32 cores/node core and 496GB of memory
#SBATCH -J job_mpi_omp
#SBATCH --time=0:55:00
#SBATCH --output %x.%j.out

source ../trunk/LMDZ.COMMON/arch/arch-ifort_MESOIPSL.env

export OMP_NUM_THREADS=2
export OMP_STACKSIZE=400M

mpirun gcm_64x48x54_phymars_para.e > gcm.out 2>&1
</syntaxhighlight>

Note that there is a per-user limitation of (maximum) 96 cores for a given job.

== Sending data on Spirit ==
This function could be used to send data to your scratch directory on spirit.
<syntaxhighlight lang="bash">
function rsend {
a=${1:-.}
b=${2:-$a}
c=${3:-spirit}
rsync -avzl $a/ $c:/scratchx/$USER/$b/
}
</syntaxhighlight>

To be used as such:
<syntaxhighlight lang="bash">
rsend folder # simply send folder to your scratch dir
rsend folder1 folder2 # send folder1 into folder2
rsend folder1 folder2 machine #send folder1 into folder2 on machine (depends on your ssh config)
</syntaxhighlight>

[[Category:FAQ]]

Using the MESOIPSL cluster

2025-02-26T13:53:45Z

Mwolff: /* Compiling the PCMs on Spirit */

This page provides some information for those who use the MESOIPSL clusters (also known as "spirit", replacing "ciclad").

Note that there are two distinct MESOIPSL Spirit clusters, one in Sorbonne Université (SU), and one in Ecole Polytechnique (X). If you log on to "spirit1" or "spirit2" (as shown below) then you are on the SU-Spirit cluster whereas if you log on to "spiritx1" or "spiritx2" then you are on the X-Spirit cluster.

If you need to run on GPUs, that is possible using the 3rd MESOIPSL cluster, HAL.

== How to access the cluster ==
If you had an account on Ciclad, then you have one on Spirit. If you need to open an account (this is of course reserved to IPSL users) then proceed to this page: https://documentations.ipsl.fr/spirit/getting_started/account.html

Once you have an account you can ssh to the cluster via either of the spirit1 or spirit2 login nodes:
<syntaxhighlight lang="bash">
ssh yourMESOIPSLlogin@spirit1.ipsl.fr
</syntaxhighlight>
or equivalently
<syntaxhighlight lang="bash">
ssh yourMESOIPSLlogin@spirit2.ipsl.fr
</syntaxhighlight>

IMPORTANT: the required ssh authentication level is such that it requires ED25519 or RSA (4096 bits) key types. If your ssh to the machines fails, the first thing to check is that you indeed are using RSA keys.

Here is probably also the right place to point to the MEOIPSL cluster's main page: https://documentations.ipsl.fr/spirit/

== OS and disk space ==
As the welcome message will remind you:
<pre>
Welcome to Ubuntu 20.04.5 LTS (GNU/Linux 5.4.0-125-generic x86_64)
CPU AMD EPYC 7402P 24-Core Processor 2.8GHz
=========================================================================
* Mesocentre ESPRI IPSL (Cluster Spirit) JUSSIEU *
=========================================================================
** Disk Space :
- /home/login (32Go and 300000 files max per user) : Backup every day.
- /data/login ( 1To and 300000 files max per user) : NO BACKUP
- /scratchu/login ( 2To and 300000 files max per user) : NO BACKUP
- /bdd/ : Datasets
- /climserv-home/, /homedata ,/scratchx : SpiritX workspace ( READ-ONLY)
------------------------------------------------------------------------------
Migration Documentation ( Temporary URL )
https://documentations.ipsl.fr/spirit/spirit_clusters/migration_from_ciclad_climserv.html
** Support Contact mailto:meso-support@ipsl.fr
------------------------------------------------------------------------------
</pre>
This is Ubuntu Linux and the "HOME" is quite limited in size. Most work should be done on the '''data''' and/or '''scratchu''' disks.

It is up to you to tailor your environment. By default it is quite bare; it is up to you to load the modules you'll need to have access to specific software or compilers or libraries (and versions thereof).
To know what modules are available:
<syntaxhighlight lang="bash">
module avail
</syntaxhighlight>
To load a given module, here the Panoply software:
<syntaxhighlight lang="bash">
module load panoply
</syntaxhighlight>

== Compiling the PCMs on Spirit ==
Dedicated arch files are available in the '''LMDZ.COMMON/arch''' subdirectory! They are labeled '''ifort_MESOIPSL''' (XIOS and DYNAMICO also have similarly named arch files).

Likewise there is a dedicated '''install_ioipsl_ifort_MESOIPSL.bash''' install script for IOIPSL available in '''LMDZ.COMMON/ioipsl'''

To compile the utilities, you should define the three varibles below as indicated, where the first line may have caused problems if you already tried it:
 NETCDF_HOME=$NETCDF_FORTRAN_ROOT
 COMPILER="ifort"
 COMPILER_OPTIONS="-O2 -ip"

== Example of a job to run a GCM simulation ==
Here to run using 24 MPI tasks with 2 OpenMP threads each:
<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=24
#SBATCH --cpus-per-task=2
#SBATCH --partition=zen4 # zen4: 64cores/node and 240GB of memory
##SBATCH --partition=zen16 # zen16: 32 cores/node core and 496GB of memory
#SBATCH -J job_mpi_omp
#SBATCH --time=0:55:00
#SBATCH --output %x.%j.out

source ../trunk/LMDZ.COMMON/arch/arch-ifort_MESOIPSL.env

export OMP_NUM_THREADS=2
export OMP_STACKSIZE=400M

mpirun gcm_64x48x54_phymars_para.e > gcm.out 2>&1
</syntaxhighlight>

Note that there is a per-user limitation of (maximum) 96 cores for a given job.

== Sending data on Spirit ==
This function could be used to send data to your scratch directory on spirit.
<syntaxhighlight lang="bash">
function rsend {
a=${1:-.}
b=${2:-$a}
c=${3:-spirit}
rsync -avzl $a/ $c:/scratchx/$USER/$b/
}
</syntaxhighlight>

To be used as such:
<syntaxhighlight lang="bash">
rsend folder # simply send folder to your scratch dir
rsend folder1 folder2 # send folder1 into folder2
rsend folder1 folder2 machine #send folder1 into folder2 on machine (depends on your ssh config)
</syntaxhighlight>

[[Category:FAQ]]

Tool Box Mars PCM

2025-02-26T10:30:24Z

Mwolff:

== Post-processing tools provided with the Mars PCM ==
First and foremost there are a number of postprocessing utilities (self-standing tools) which can be found in the
<pre>
LMDZ.MARS/util
</pre>
directory; you certainly want to first read the README file there.

Current contents of this directory is:
<pre>
aeroptical.def extract.F90 lslin.def startarchive2icosa/
aeroptical.F90 extract.points.def lslin.F90 streamfunction.F90
aeropt_mod.F90 extract.profile.def README xvik/
compile hrecast.def simu_MCS.def zrecast.auto.def
concatnc.def hrecast.F90 simu_MCS.F90 zrecast.F90
concatnc.F90 localtime.def solzenangle.def zrecast.manual.def
expandstartfi.F90 localtime.F90 solzenangle.F90
</pre>
the ''compile'' script is an example of how to compile any of the utilities, which you will have to adapt to your needs (mostly concerns setting the right path to the NetCDF library). All the post-processing tools are meant to be run interactively (asking the user for some instructions), hence the ''*.def'' files as it is most of the time more convenient (once one knows the tools and questions it will ask) to redirect this list of answers to the standard input of the tool, e.g.
<syntaxhighlight lang="bash">
zrecast.e < zrecast.manual.def
</syntaxhighlight>

== Main programs (other than GCM) but included in the Mars PCM package ==
There are a few other main programs that are included with the GCM.

Advanced stuff: In practice these main programs are located under ''LMDZ.MARS/dynphy_lonlat/phymars/'' as they are at the interface between lon-lat dynamics and the Mars physics package (i.e. need to use both and thus can only be applied in that context).

=== start2archive ===
A main program to collect multiple <code>start.nc</code> and <code>startfi.nc</code> files from a series simulations and store them in a <code>start_archive.nc</code> file. For this one simply needs to run the <code>startarchive</code> program in the directory. It will automatically fetch code>start.nc</code> and <code>startfi.nc</code> files and generate <code>start_archive.nc</code>. If a <code>start_archive.nc</code> file is already present then the current <code>start.nc</code> and <code>startfi.nc</code> files are added to the <code>start_archive.nc</code> file (which can contain multiple initial states, as long as they are on the same grid and correspond to different dates.

=== newstart ===
A main program to:
* extract (and interpolate) <code>restart.nc</code> and <code>restartfi.nc</code> files from a <code>start_archive.nc</code> file or from a pair of <code>start.nc</code> and <code>startfi.nc</code> files. The subtle difference between the two setup is that grid interpolation (horizontal and/or vertical) is only possible if using a <code>start_archive.nc</code> input file
* modify values and fields contained in the initial condition file
* Compiling <code>newstart</code> is done using the [[The makelmdz fcm GCM Compilation Script|makelmdz_fcm]] utility. The program is then meant to be run interactively with the user providing options and choices when prompted.
* Once the program has run and finished without error, it will generate <code>restart.nc</code> and <code>restartfi.nc</code>

=== xvik ===
A post-processing utility to analyse the modeled CO2 cycle

== testphys1d ==
More than a pre- or post-processing tool, this is a 1D (single column) version of the PCM. More about it is on the dedicated page: [[Mars 1D testphys1d program]].

Note that there is also a separate "self-standing" 1D model, the "1D thermal model", which can be downloaded from this page: [http://www-planets.lmd.jussieu.fr/ http://www-planets.lmd.jussieu.fr/]. This is essentially a frozen version of ''testphys1d'' with some additional tweaks to make it more user-friendly.

== Visualizing the outputs ==
The GCM and most of the post-processing tools mentioned above produce NetCDF files, which one most likely will need to visualize.
There are a number of tools available (free or not). Here is a selection:
* Ncview is a very basic tool, mostly useful for a simple quick look.
* Panoply is a user-friendly tool for viewing NetCDF data, available here: https://www.giss.nasa.gov/tools/panoply/
* Ferret is another nice tool for viewing and processing NetCDF data, see their official page: https://ferret.pmel.noaa.gov/Ferret/ and also [[Some Ferret tips and pointers|this page]]
* Many also like to write up their own python scripts

== Maniuplating NetCDF files with external tools ==
In addition to the programs that come with the Mars PCM distribution, there are many public tools available that provide more general capabilities. Here are some selections that you may
find to be of value:
* NetCDF Operators (NCO): This toolbox is a combination of compiled programs and scripts for manipulating NetCDF files, including regridding and interpolating. This public domain tools was developed at the University of California - Irvine and appears to be actively maintained. Find it (along with documentation) at the official site: https://nco.sourceforge.net. A reasonable tutorial, though it is html based and a few years old (like playing an Atari console game), may be downloaded here: https://www.hydroshare.org/resource/4b5a903a02e64b078d5a581a010f45a4/

[[Category:Mars-Model]]
[[Category:Mars-1D]]

Tool Box Mars PCM

2025-02-26T10:29:00Z

Mwolff:

Some pointers about the subversion (svn) tool

2023-11-01T11:18:27Z

Mwolff: /* The subversion (a.k.a svn) tool */

== The subversion (a.k.a. svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. This is quite similar to the also well-known git tool. But we do not wish to have a religious debate.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands of potential use in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Some_pointers_about_the_subversion_(svn)_tool#svn_status svn status] tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:16:47Z

Mwolff: /* Some example commands potentially useful in preparing a commit */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands of potential use in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Some_pointers_about_the_subversion_(svn)_tool#svn_status svn status] tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:15:42Z

Mwolff: /* Removing a file from the commit list using svn revert */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands potentially useful in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Some_pointers_about_the_subversion_(svn)_tool#svn_status svn status] tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:11:49Z

Mwolff: /* Removing a file from the commit list using svn revert */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands potentially useful in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Some_pointers_about_the_subversion_(svn)_tool#svn_status svn status] tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:09:32Z

Mwolff: /* Removing a file from the commit list using svn revert */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands potentially useful in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see [https://lmdz-forge.lmd.jussieu.fr/mediawiki/Planets/index.php/Some_pointers_about_the_subversion_(svn)_tool#svn_status svn status] tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[svn_status test]]

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:06:36Z

Mwolff: /* Some other useful commands in preparing a commit */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some example commands potentially useful in preparing a commit ==

=== Removing a file from the commit list using ''svn revert'' ===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see "svn status" tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T11:03:39Z

Mwolff: /* Some other useful commands in preparing a commit */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some other useful commands in preparing a commit ==

===Removing a file from the commit list using "svn revert"===

In order to see only the files that are part of the versioned archive, it may be convenient to request only those (see "svn status" tutorial above). However, this may reveal files that you do not intend to commit. The example here is from the LMD.MARS/util directory where one had modified three (versioned) files

<syntaxhighlight lang="bash">
%svn status -q
M aeroptical.F90
M compile
M simu_MCS.F90
</syntaxhighlight>

The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T10:54:59Z

Mwolff: /* Removing a file from the commit list using "svn revert" */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some other useful commands in preparing a commit ==

=== svn status ===

This command produces a listing of files that are flagged as modified, unknown, to be deleted, etc. In order to only see the files that are part of the versioned archive, it may be convenient to request only those (otherwise you may get a long list of files flagged with a "?" for executables, libraries, etc.:

<syntaxhighlight lang="bash">
svn status -q
</syntaxhighlight>
The above command was executed in the LMD.MARS/util directory where one had modified three (versioned) files. This results in the following output.
<pre>
M aeroptical.F90
M compile
M simu_MCS.F90
</pre>

The "svn help status" command is very helpful in learning a little more about status.

===Removing a file from the commit list using "svn revert"===

The above example includes a file that we do NOT want to commit. The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. '''NOTE''' that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T10:53:41Z

Mwolff: /* Some other useful commands in preparing a commit */

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some other useful commands in preparing a commit ==

=== svn status ===

This command produces a listing of files that are flagged as modified, unknown, to be deleted, etc. In order to only see the files that are part of the versioned archive, it may be convenient to request only those (otherwise you may get a long list of files flagged with a "?" for executables, libraries, etc.:

<syntaxhighlight lang="bash">
svn status -q
</syntaxhighlight>
The above command was executed in the LMD.MARS/util directory where one had modified three (versioned) files. This results in the following output.
<pre>
M aeroptical.F90
M compile
M simu_MCS.F90
</pre>

The "svn help status" command is very helpful in learning a little more about status.

===Removing a file from the commit list using "svn revert"===

The above example includes a file that we do NOT want to commit. The "compile" file was modified to find the NETCDF library on the local machine, but we do not want to add this to the archive (and annoy Ehouarn). So, we execute the command below which will replace the current version of compile with that of the current revision with which one is working. **NOTE** that if you need that version of the file, you should copy it to a different location or file name since it is replaced with a "fresh" copy.

<syntaxhighlight lang="bash">
% svn revert compile
Reverted 'compile'

% svn status -q
M aeroptical.F90
M simu_MCS.F90
</syntaxhighlight>
And now one is ready to proceed to the next step of the commit.

[[Category:FAQ]]

Some pointers about the subversion (svn) tool

2023-11-01T10:34:35Z

Mwolff:

== The subversion (a.k.a svn) tool ==
The subversion (svn) tool is what is used to keep track of the various versions of the PCM source codes. Quite similar to the also well known git tool.

== Some useful svn commands ==

==== svn checkout ====
A checkout is simply downloading the (latest version of) reference code from the svn repository and saving a local copy. e.g. to download the entire PCM repository (i.e. "trunk" directory and sub-directories):
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>
You can add an argument to rename the directory "trunk" to whatever you want, e.g. "PCM_sources"
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk PCM_sources
</syntaxhighlight>
Note that if you don't want to download the entire repository (likely the case if using only one of the PCMs) you can start by downloading an empty image of the "trunk":
<syntaxhighlight lang="bash">
svn checkout https://svn.lmd.jussieu.fr/Planeto/trunk --depth empty
</syntaxhighlight>
And later use "svn update" in "trunk" to only update desired sub-directories.

It is also possible to download a given revision of the trunk with "--revision ###" (where ### is the revision number), e.g. to download revision 1567:
<syntaxhighlight lang="bash">
svn --revision 1567 checkout https://svn.lmd.jussieu.fr/Planeto/trunk
</syntaxhighlight>

==== svn update ====
To update your working copy to the latest revision, in your "trunk" directory issue command:
<syntaxhighlight lang="bash">
svn update
</syntaxhighlight>
Note that you can "update" to any revision number (including past ones) by specifying revision number, e.g. to update (or revert) to revision 2567:
<syntaxhighlight lang="bash">
svn update --revision 2567
</syntaxhighlight>

==== svn status ====
To know what files have been changes (with respect to your reference revision) or deleted or added in your distribution, use
<syntaxhighlight lang="bash">
svn status
</syntaxhighlight>
which will return a list of files/directories changes. In practice each item of the list is prefixed by <code>?</code> if the file is not versioned (i.e. not part of the svn repository), <code>!</code> if it is missing (whereas it exists in the repository) or <code>M</code> if it is a modified version (i.e. you edited the file and made some changes to it, with respect to the reference)

==== svn diff ====
This command generates a "diff" between your local changes and local reference version, without extra arguments:
<syntaxhighlight lang="bash">
svn diff
</syntaxhighlight>
The report will be for all files in current directory and sub-directories. One may add as a third argument the name of a given file to have only the diff concerning that file.

==== svn revert ====
If you have modified (or even deleted) a versioned file but want it back to its original pristine version, rather than undo the changes manually you can simply invoke:
<syntaxhighlight lang="bash">
svn revert thefileyouwantrestored
</syntaxhighlight>

==== svn log ====
If you want to list all the revision messages (when one commits changes, one usually documents it with a short summary) use
<syntaxhighlight lang="bash">
svn log
</syntaxhighlight>
Note that this will give you all the messages (logs) since the beginning of the repository...

If you know which revision number's log you want, you can specify it using <code>--revision ###</code>. e.g. to list the log for revision 666 only:
<syntaxhighlight lang="bash">
svn log --revision 666
</syntaxhighlight>
And to list the latest log without specifying the revision number:
<syntaxhighlight lang="bash">
svn log --revision HEAD
</syntaxhighlight>

== For experts: how to commit your changes ==
IMPORTANT: This only concerns you if you are included in the core team of developers with commit privileges.

# You must be online (committing requires to connect and interact with the svn server)
# You must have made you changes on (svn) versioned code, and that it is up-to-date with the repository ("svn update" is your friend).
# It is recommended that you have set your ''SVN_EDITOR'' environment variable to point to your favorite text editor. For instance "vi":
<syntaxhighlight lang="bash">
declare -x SVN_EDITOR=vim
</syntaxhighlight>

Now that things are ready for the commit (you might want to check one last time with "svn diff" that all your changes are in place and that you cleaned up any intermediate stuff), you can, in the directory where you made the changes, run the command:
<syntaxhighlight lang="bash">
svn commit
</syntaxhighlight>
Note that if you want to only commit some files and not all those you modified in the current directory and subdirectories, you can can specify explicitely the paths&names of files to commit as extra arguments to "svn commit"

Once the "svn commit" command launched, your editor will open up, pre-filled with the differences in the code implied by your changes automatically inserted. All you need to do is fill in the first part of the message with comments about your changes (e.g. bug fix of ... , added feature as ..., code tidying, etc.). usually a few lines suffice. It is common practice to state in the first line of the commit which PCM is concerned ("Mars PCM", "Generic PCM", "Venus PCM", ...) and to sign the commit with your initials. Once you have entered your message, just save the file and this will automatically trigger the commit.

Once the commit triggered, you will need to specify you svn account login and password, at least the first time (svn can save and store these so that you don't need to enter them every time).

== Some typical svn errors you may run into ==
If when trying t use an svn command you get a message of the likes of:
<pre>
svn: E155036: The working copy at ....
is too old (format 29) to work with client version '1.10.2 (r1835932)' (expects format 31). You need to upgrade the working copy first.
</pre>
This simply means that your svn tool has been upgraded to a more recent version and that you need to upgrade your current repository to follow up. In order to do that simply do
<syntaxhighlight lang="bash">
svn upgrade
</syntaxhighlight>
And then you can keep using svn as before.

== Some other useful commands in preparing a commit ==

[[Category:FAQ]]

Some Ferret tips and pointers

2023-10-24T06:29:00Z

Mwolff: /* Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023) */

Some Ferret tips and pointers

2023-10-24T06:27:43Z

Mwolff: /* Miniconda */

Some Ferret tips and pointers

2023-10-24T06:27:18Z

Mwolff: /* Mac OSX (PyFerret) and Graphics bug */

Some Ferret tips and pointers

2023-10-17T14:58:15Z

Mwolff: /* Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023) */

Some Ferret tips and pointers

2023-10-17T14:54:56Z

Mwolff: /* Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023) */

File:Ferret testplot coads.png

2023-10-17T14:53:11Z

Mwolff: test plot for Ferret from coads climatology

test plot for Ferret from coads climatology

Some Ferret tips and pointers

2023-10-17T13:09:19Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T13:06:34Z

Mwolff: /* Commands used on a Macbook Pro with the M2 ARM chipset (summer 2023) */

Some Ferret tips and pointers

2023-10-17T12:54:24Z

Mwolff: /* Mac OSX (PyFerret) and Graphics bug */

Some Ferret tips and pointers

2023-10-17T12:35:24Z

Mwolff: /* Installation tips */

Some Ferret tips and pointers

2023-10-17T12:14:14Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T06:19:14Z

Mwolff: /* Graphics bug in Mac OSX version as of summer 2023 */

Some Ferret tips and pointers

2023-10-17T06:18:19Z

Mwolff: /* Installation tips */

Some Ferret tips and pointers

2023-10-17T06:17:34Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T06:15:11Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T06:13:36Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T06:12:41Z

Mwolff: /* Various tips and pointers */

Some Ferret tips and pointers

2023-10-17T06:11:50Z

Mwolff:

Some Ferret tips and pointers

2023-10-17T05:49:38Z

Mwolff: /* Ferret */

Some Ferret tips and pointers

2023-10-17T05:48:30Z

Mwolff: /* Ferret */

Quick Install and Run Mars PCM

2023-04-11T08:38:25Z

Mwolff: Created page with " == Dude, on est là. =="

== Dude, on est là. ==