Skip to content

Commit 781db16

Browse files
RubenChMRubenChM
committed
Add Global Properties documentation
1 parent 7eaee08 commit 781db16

File tree

3 files changed

+210
-1
lines changed

3 files changed

+210
-1
lines changed

‎biobb_common/docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@
7676
# The short X.Y version.
7777
version = u'5.1.0'
7878
# The full version, including alpha/beta/rc tags.
79-
release = u'2024.2'
79+
release = u'2025.1'
8080

8181
# The language for content autogenerated by Sphinx. Refer to documentation
8282
# for a list of supported languages.

‎biobb_common/docs/source/global_properties.rst‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
BioBB Global Properties
2+
=======================
3+
4+
Overview
5+
--------
6+
7+
The ``BioBBGlobalProperties`` class provides a centralized way to manage global configuration properties that are shared across all BiobbObject instances in your workflow. This eliminates the need to pass the same properties repeatedly to each building block.
8+
9+
Features
10+
--------
11+
12+
- **Global Configuration**: Set properties once and use them across all BioBB objects
13+
- **Priority System**: Local properties override global properties when conflicts arise
14+
- **Dictionary Interface**: Behaves like a standard Python dictionary
15+
- **Shallow Copy Support**: Safe property sharing without unintended modifications
16+
17+
Usage
18+
-----
19+
20+
Basic Usage
21+
~~~~~~~~~~~
22+
23+
The global properties instance is automatically created and available for import:
24+
25+
.. code-block:: python
26+
27+
from biobb_common import biobb_global_properties
28+
29+
# Set global properties
30+
biobb_global_properties.update({
31+
'container_path': '/usr/bin/singularity',
32+
'container_image': 'biocontainers/gromacs:latest',
33+
'remove_tmp': True,
34+
'restart': False
35+
})
36+
37+
Setting Properties
38+
~~~~~~~~~~~~~~~~~~
39+
40+
You can set properties using dictionary-style operations:
41+
42+
.. code-block:: python
43+
44+
# Set individual properties
45+
biobb_global_properties['binary_path'] = '/usr/local/bin/gmx'
46+
biobb_global_properties['timeout'] = 3600
47+
48+
# Set multiple properties at once
49+
biobb_global_properties.update({
50+
'container_volume_path': '/data',
51+
'container_working_dir': '/tmp',
52+
'disable_logs': False
53+
})
54+
55+
Using with BioBB Objects
56+
~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
When creating BioBB objects, global properties are automatically merged with local properties:
59+
60+
.. code-block:: python
61+
62+
from biobb_gromacs.gromacs.mdrun import mdrun
63+
from biobb_common import biobb_global_properties
64+
65+
# Set global properties once
66+
biobb_global_properties.update({
67+
'container_path': '/usr/bin/singularity',
68+
'container_image': 'biocontainers/gromacs:latest',
69+
'remove_tmp': True
70+
})
71+
72+
# Create BioBB object - global properties are automatically applied
73+
mdrun_obj = mdrun(
74+
input_tpr_path='input.tpr',
75+
output_trr_path='output.trr',
76+
output_gro_path='output.gro',
77+
output_edr_path='output.edr',
78+
output_log_path='output.log',
79+
properties={
80+
'mpi_bin': 'mpirun', # This local property is added
81+
'timeout': 7200 # This overrides global timeout if set
82+
}
83+
)
84+
85+
Property Priority
86+
~~~~~~~~~~~~~~~~~
87+
88+
Local properties always take precedence over global properties:
89+
90+
.. code-block:: python
91+
92+
# Global setting
93+
biobb_global_properties['timeout'] = 3600
94+
95+
# Local setting overrides global
96+
my_object = SomeBioBBClass(
97+
properties={
98+
'timeout': 7200 # This value will be used, not 3600
99+
}
100+
)
101+
102+
Common Use Cases
103+
----------------
104+
105+
Container Configuration
106+
~~~~~~~~~~~~~~~~~~~~~~~
107+
108+
Set container settings once for all building blocks:
109+
110+
.. code-block:: python
111+
112+
biobb_global_properties.update({
113+
'container_path': '/usr/bin/singularity',
114+
'container_image': 'biocontainers/gromacs:2021.1--h_fbb9dd7_1',
115+
'container_volume_path': '/data',
116+
'container_working_dir': '/tmp'
117+
})
118+
119+
Workflow-wide Settings
120+
~~~~~~~~~~~~~~~~~~~~~~
121+
122+
Configure common workflow properties:
123+
124+
.. code-block:: python
125+
126+
biobb_global_properties.update({
127+
'remove_tmp': True,
128+
'restart': False,
129+
'sandbox_path': './workflow_sandbox',
130+
'disable_logs': False
131+
})
132+
133+
Environment Variables
134+
~~~~~~~~~~~~~~~~~~~~~
135+
136+
Set environment variables for all containers:
137+
138+
.. code-block:: python
139+
140+
biobb_global_properties['env_vars_dict'] = {
141+
'OMP_NUM_THREADS': '4',
142+
'CUDA_VISIBLE_DEVICES': '0',
143+
'GMX_MAXBACKUP': '-1'
144+
}
145+
146+
Best Practices
147+
--------------
148+
149+
1. **Set Early**: Configure global properties at the beginning of your workflow
150+
2. **Use for Common Settings**: Apply to properties shared across multiple building blocks
151+
3. **Override When Needed**: Use local properties for block-specific configurations
152+
4. **Clear Documentation**: Document which properties are set globally in your workflow
153+
154+
Example Workflow
155+
----------------
156+
157+
.. code-block:: python
158+
159+
from biobb_common import biobb_global_properties
160+
from biobb_gromacs.gromacs.editconf import editconf
161+
from biobb_gromacs.gromacs.solvate import solvate
162+
from biobb_gromacs.gromacs.mdrun import mdrun
163+
164+
# Configure global properties once
165+
biobb_global_properties.update({
166+
'container_path': '/usr/bin/singularity',
167+
'container_image': 'biocontainers/gromacs:latest',
168+
'remove_tmp': True,
169+
'restart': False,
170+
'env_vars_dict': {
171+
'OMP_NUM_THREADS': '8'
172+
}
173+
})
174+
175+
# All building blocks will inherit these properties
176+
editconf_step = editconf(
177+
input_gro_path='input.gro',
178+
output_gro_path='editconf.gro'
179+
)
180+
181+
solvate_step = solvate(
182+
input_solute_gro_path='editconf.gro',
183+
output_gro_path='solvated.gro',
184+
properties={
185+
'shell': 1.0 # Local property specific to solvate
186+
}
187+
)
188+
189+
mdrun_step = mdrun(
190+
input_tpr_path='input.tpr',
191+
output_trr_path='output.trr',
192+
properties={
193+
'timeout': 7200 # Override global timeout for this step
194+
}
195+
)
196+
197+
API Reference
198+
-------------
199+
200+
.. autoclass:: biobb_common.BioBBGlobalProperties
201+
:members:
202+
:undoc-members:
203+
:show-inheritance:
204+
205+
.. autodata:: biobb_common.biobb_global_properties
206+
:annotation: = BioBBGlobalProperties()
207+
208+
Global instance of BioBBGlobalProperties available for immediate use.

‎biobb_common/docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Contents
1616
:maxdepth: 1
1717

1818
Introduction & installation <readme>
19+
Global Properties <global_properties>
1920
API Documentation <modules>
2021
Changelog <change_log>
2122

0 commit comments

Comments
 (0)